GET /jobs

Retrieve details about all jobs that the orchestrator knows about.

Request format

When Forming orchestrator API requests to this endpoint, you can append parameters to the end of the URI path, such as:

https://orchestrator.example.com:8143/orchestrator/v1/jobs?limit=20&offset=20

These parameters are available:

Parameter	Definition
`limit`	Set the maximum number of jobs to include in the response. The point at which the `limit` count starts is determined by `offset`, and the job record sort order is determined by `order_by` and `order`.
`offset`	Specify a zero-indexed integer at which to start returning results. For example, if you set this to `12`, the response returns jobs starting with the 13th record. The default is `0`.
`order_by`	Specify one of the following categories to use to sort the results: `owner`, `timestamp`, `environment`, `name`, or `state`. Sorting by `owner` uses the `login` subfield of `owner` records.
`order`	Indicate whether results are returned in ascending (`asc`) or descending (`desc`) order. The default is `asc`.
`type`	Specify a job type to query, either `deploy`, `task`, or `plan_task`.
`task`	Specify a task name to match. Partial matches are supported. If you specified `type=deploy`, you can't use `task`.
`min_finish_timestamp`	Returns only the jobs that finished at or after the supplied UTC timestamp.
`max_finish_timestamp`	Returns only the jobs that finished at or before the supplied UTC timestamp.

Response format

The response is a JSON object containing an array, called items, and an object, called pagination.

The items array contains a JSON object for each job. Each object uses these keys to provide job details:

Key	Definition
`id`	An absolute URL that links to the newly created job.
`name`	A stringified number identifying the newly created job. You can use this with other endpoints, such as GET /jobs/<job-id> (retrieve information about the status of the job) and POST /command/stop.
`state`	The job's current state: `new`, `ready`, `running`, `stopping`, `stopped`, `finished`, or `failed` If you want to know when a job entered and exited each state, use the GET /jobs/<job-id> endpoint.
`command`	The command that created the job.
`type`	The job type: `deploy`, `task`, `plan_task`, `plan_script`, `plan_upload`, `plan_command`, `plan_wait`, `plan_apply`, `plan_apply_prep`
`options`	Options used to create the job (based on the `command`), a `description` of the job, and the `environment` the job operated in. Previously, the `description` and `environment` key were separate from `options`. However, these are deprecated. Refer to the keys in `options` instead.
`owner`	The subject ID, login, and other details of the user that requested the job.
`timestamp`	The time when the job's `state` last changed.
`started_timestamp`	The time the job was created and started.
`finished_timestamp`	The time the job finished.
`duration`	If the job is finished, this is the number of seconds the job took to run. If the job is still running, this is the number of seconds the job has been running.
`node_count`	The number of nodes the job ran on.
`node_states`	A JSON map containing the number of nodes involved with the job categorized by current node state. States with no nodes are omitted. If there were no nodes associated with the job, this value is `null`.
`nodes`	A link to get more information about the nodes participating in a given job. You can use this with the GET /jobs/<job-id>/nodes endpoint.
`report`	A link to the report for a given job. You can use this with the GET /jobs/<job-id>/report endpoint.
`events`	A link to the events for a given job. You can use this with the GET /jobs/<job-id>/events endpoint.
`userdata`	An object of arbitrary key/value data supplied to the job.

The pagination object uses these keys:

total: The total number of job records in the collection, regardless of limit and offset.
limit, offset, order_by, order, and type: Reflects values supplied in the request. If you specified a value, these key shows the value you specified. If you did not specify a value, the key shows the default value.

Here is an example response describing two jobs and pagination information:

{
  "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
      "name": "1234",
      "state": "finished",
      "command": "deploy",
      "type": "deploy",
      "node_count": 5,
      "node_states": {
        "finished": 2,
        "errored": 1,
        "failed": 1,
        "running": 1
      },
      "options": {
        "concurrency": null,
        "noop": false,
        "trace": false,
        "debug": false,
        "scope": {},
        "enforce_environment": true,
        "environment": "production",
        "evaltrace": false,
        "target": null,
        "description": "deploy the web app"
      },
      "owner" : {
        "email" : "admin@example.com",
        "is_revoked" : false,
        "last_login" : "2020-05-05T14:03:06.226Z",
        "is_remote" : true,
        "login" : "admin",
        "inherited_role_ids" : [ 2 ],
        "group_ids" : [ "9a588fd8-3daa-4fc2-a396-bf88945def1e" ],
        "is_superuser" : false,
        "id" : "751a8f7e-b53a-4ccd-9f4f-e93db6aa38ec",
        "role_ids" : [ 1 ],
        "display_name" : "Admin",
        "is_group" : false
      },
      "description": "deploy the web app",
      "timestamp": "2016-05-20T16:45:31Z",
      "started_timestamp": "2016-05-20T16:41:15Z",
      "finished_timestamp": "2016-05-20T16:45:31Z",
      "duration": "256.0",
      "environment": {
        "name": "production"
      },
      "report": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/report"
      },
      "events": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/events"
      },
      "nodes": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/nodes"
      },
      "userdata": {
        "servicenow_ticket": "INC0011211"
      }
    },
    {
      "description": "",
      "report": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/report"
      },
      "name": "1235",
      "events": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/events"
      },
      "command": "plan_task",
      "type": "plan_task",
      "state": "finished",
      "nodes": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/nodes"
      },
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235",
      "environment": {
        "name": ""
      },
      "options": {
        "description": "",
        "plan_job": 197,
        "noop": null,
        "task": "facts",
        "sensitive": [],
        "scheduled-job-id": null,
        "params": {},
        "scope": {
          "nodes": [
            "orchestrator.example.com"
          ]
        },
        "project": {
          "project_id": "foo_id",
          "ref": "524df30f58002d30a3549c52c34a1cce29da2981"
        }
      },
      "timestamp": "2020-09-14T18:00:12Z",
      "started_timestamp":  "2020-09-14T17:59:05Z",
      "finished_timestamp":  "2020-09-14T18:00:12Z",
      "duration": "67.34",
      "owner": {
        "email": "",
        "is_revoked": false,
        "last_login": "2020-08-05T17:54:07.045Z",
        "is_remote": false,
        "login": "admin",
        "is_superuser": true,
        "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd",
        "role_ids": [
          1
        ],
        "display_name": "Administrator",
        "is_group": false
      },
      "node_count": 1,
      "node_states": {
        "finished": 1
      },
      "userdata": {}
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "order": "asc",
    "order_by": "timestamp",
    "total": 2,
    "type": ""
  }
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 400 puppetlabs.orchestrator/validation-error response if there is a problem with a supplied parameter, such as the limit parameter not being formatted as an integer.