GET /plan_jobs

Retrieve details about all plan 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/plan_jobs?limit=20&order=desc

These parameters are available:

Parameter	Definition
limit	Set the maximum number of plan 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.
results	Whether you want the response to include or exclude plan output. The default is include.
min_finish_timestamp	Returns only the plan jobs that finished at or after the supplied UTC timestamp.
max_finish_timestamp	Returns only the plan 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 plan job. Each object uses these keys to provide plan job details:

Key	Definition
id	The plan job's absolute URL, which includes the plan job's ID.
name	A stringified number identifying the plan job.
state	The plan job's current state: pending, running, success, or failure If you want to know when a plan job entered and exited each state, use the GET /plan_jobs/<job-id> endpoint.
options	A JSON object containing plan job options, including: description: A user-provided description of the plan job. plan_name: The name of the plan that ran. parameters: Parameters supplied to the plan job, such as target nodes. scheduled_job_id: A job ID, if the plan ran as a scheduled job. Otherwise, the value is null. environment: The environment the plan ran in. Omitted if not applicable. sensitive: Password or SSH details supplied to the plan. Empty if not applicable. project: Project information, such as a project_id and ref. Omitted if not applicable.
result	Plan output resulting from running the plan job. Omitted if you supplied results=exclude in the request.
owner	The subject ID, login, and other details of the user that requested the plan job.
created_timestamp	The time the plan job was created.
finished_timestamp	The time the plan job finished, or null if the job is currently running.
duration	If the plan job is finished, this is the number of seconds the job took to run. If the plan job is still running, this is the number of seconds the job has been running.
events	A link to the events associated with a plan job. You can use this with the GET /plan_jobs/<job-id>/event/<event-id> 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 and offset: 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 plan jobs and pagination information:

{
  "items": [
    {
      "finished_timestamp": "2020-09-23T18:00:13Z",
      "name": "38",
      "events": {
        "id": "https://orchestrator.example.com:8143:8143/orchestrator/v1/plan_jobs/38/events"
      },
      "state": "success",
      "result": [
        "orchestrator.example.com: CentOS 7.2.1511 (RedHat)"
      ],
      "id": "https://orchestrator.example.com:8143:8143/orchestrator/v1/plan_jobs/38",
      "created_timestamp": "2020-09-23T18:00:08Z",
      "duration": 123.456,
      "options": {
        "description": "just the facts",
        "plan_name": "facts::info",
        "parameters": {
          "targets": "orchestrator.example.com"
        },
        "sensitive": [],
        "scheduled_job_id": "116",
        "project" : {
          "project_id": "myproject_id",
          "ref": "524df30f58002d30a3549c52c34a1cce29da2981"
        }
      },
      "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
      },
      "userdata": {
        "servicenow_ticket": "INC0011211"
      }
    },
    {
      "finished_timestamp": null,
      "name": "37",
      "events": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/37/events"
      },
      "state": "running",
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/37",
      "created_timestamp": "2018-06-06T20:22:08Z",
      "duration": 123.456,
      "options": {
        "description": "Testing myplan",
        "plan_name": "myplan",
        "parameters": {
          "nodes": [
            "orchestrator.example.com"
          ]
        },
        "sensitive": ["secret"],
        "environment": "production",
        "scheduled_job_id": null
      },
      "owner": {
        "email": "",
        "is_revoked": false,
        "last_login": "2018-06-06T20:22:06.327Z",
        "is_remote": false,
        "login": "admin",
        "is_superuser": true,
        "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd",
        "role_ids": [
          1
        ],
        "display_name": "Administrator",
        "is_group": false
      },
      "result": null,
      "userdata": {}
    },
  ],
  "pagination": {
    "limit": 6,
    "offset": 3,
    "total": 40
  }
}

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.