Plan jobs endpoints

Use the plan_jobs endpoints to examine plan jobs and their details.

You can:

GET /plan_jobs: Retrieve details about all known plan jobs.
GET /plan_jobs/<job-id>: Retrieve details about a specific plan job.
GET /plan_jobs/<job-id>/events: Retrieve a list of events that occurred during a specific plan job.
GET /plan_jobs/<job-id>/event/<event-id>: Retrieve the details of a specific event for a specific plan job.

For details about jobs that aren't plan jobs, use the Jobs endpoints.

To stop an in-progress plan job, use POST /command/stop_plan.

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` Tip: 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>/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 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.

GET /plan_jobs/<job-id>

Retrieve details of a specific plan job, including the start and end times for each job state.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include an integer job ID identifying a specific plan job. Plan job IDs are returned in responses from plan-related Command endpoints and the GET /plan_jobs endpoint. For example, this request queries a plan job with ID 375:

https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/375

Job IDs are returned in responses from Command endpoints and the GET /jobs endpoint.

A complete request might look like:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/plan_jobs/81"

curl --insecure --header "$auth_header" "$uri"

Response format

The response is a JSON object that 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`
`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.
`owner`	The subject ID, login, and other details of the user that requested the plan job.
`timestamp`	The time when the plan job's `state` last changed.
`events`	A link to the events associated with the plan job. You can use this with the GET /plan_jobs/<job-id>/events endpoint.
`status`	A JSON object representing all jobs that ran as part of the plan. For each job, there is an array detailing each `state` the job was in while it ran, as well as the start and end times for each `state`. Job states are different from plan job states. Job states include `new`, `ready`, `running`, `stopping`, `stopped`, `finished`, and `failed`.
`userdata`	An object of arbitrary key/value data supplied to the job.

In this example response, two jobs ran as part of the plan, and each job had two states:

{
  "id": "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/1234",
  "name": "1234",
  "state": "success",
  "options": {
    "description": "This is a plan run",
    "plan_name": "package::install",
    "parameters": {
      "foo": "bar"
    }
  },
  "result": {
    "output": "test\n"
  },
  "owner": {
    "email": "",
    "is_revoked": false,
    "last_login": "YYYY-MM-DDT17:06:48.170Z",
    "is_remote": false,
    "login": "admin",
    "is_superuser": true,
    "id": "42bf351c-f9ec-40af-84ad-e976fec7f4bd",
    "role_ids": [
      1
    ],
    "display_name": "Administrator",
    "is_group": false
  },
  "timestamp": "YYYY-MM-DDT16:45:31Z",
  "status": {
    "1": [
      {
        "state": "running",
        "enter_time": "YYYY-MM-DDT18:44:31Z",
        "exit_time": "YYYY-MM-DDT18:45:31Z"
      },
      {
        "state": "finished",
        "enter_time": "YYYY-MM-DDT18:45:31Z",
        "exit_time": null
      }
    ],
    "2": [
      {
        "state": "running",
        "enter_time": "YYYY-MM-DDT18:44:31Z",
        "exit_time": "YYYY-MM-DDT18:45:31Z"
      },
      {
        "state": "failed",
        "enter_time": "YYYY-MM-DDT18:45:31Z",
        "exit_time": null
      }
    ]
  },
  "events": {
    "id": "https://localhost:8143/orchestrator/v1/plan_jobs/1234/events"
  },
  "userdata": {}
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:


Response code	Key	Description
`400`	`puppetlabs.orchestrator/validation-error`	The job ID in the request is not an integer.
`404`	`puppetlabs.orchestrator/unknown-job`	No plan job exists that matches the specified job ID.

GET /plan_jobs/<job-id>/events

Retrieve a list of events that occurred during a specific plan job.

Request format

You can use the optional start parameter to start the list of events from a specific event ID number.

For example, this request queries events associated with the 352 plan job, starting with event number 1272:

GET https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/events?start=1272

Response format

A successful response is a JSON object containing a next-events object and an items array.

The next-events object contains two subkeys:

id: The URI supplied in the request.
event: The ID of the first event returned or the start parameter, if supplied in the request.

The items array uses these keys to detail the plan job's events:


Key	Definition
`id`	An individual event's ID
`type`	Each event has one event type, determined by the event's status or circumstances that cause it to occur: `task_start`: A task run started. `script_start`: A script run starts as part of a plan. `command_start`: A command run starts as part of a plan. `upload_start`: A file upload starts as part of a plan. `wait_start`: A `wait_until_available()` call starts as part of a plan. `out_message`: As part of a plan, `out::message` is called. `apply_start`: A `puppet apply` run started as part of a plan. `apply_prep_start`: An `apply_prep` run starts as part of a plan. `plan_finished`: The plan job successfully finished. `plan_failed`: The plan job failed. A plan containing the `run_plan()` function completes the secondary plan during the primary plan job. Such subplans do not have their own plan jobs – They are included with, and completed as part of, the original job. These event types indicate when a subplan started or finished: `plan_start`: The `run_plan()` function started a plan within the current plan job. `plan_end`: The subplan, triggered by the `run_plan()` function, finished. This event type is specific to subplans and different from `plan_finished`.
`timestamp`	The time the event occurred or was created.
`details`	A JSON object containing information about the event. Specific contents depends on the event type: For any `*_start` events (except `plan_start`), details include the `job-id` of the associated action or task. For `plan_finished` and `plan_failed` events, details include the `plan-id` and `result`. For `out_message` events, details include the `message` contents, truncated to 1,024 bytes. You can use the GET /plan_jobs/<job-id>/event/<event-id> endpoint to get the full message content. For `plan_start` events, details include the `plan`, which identifies the subplan that ran within the original plan. For `plan_end` events, details include the `plan` (which is the subplan that ran within the original plan) and the `duration` (which is how long the subplan ran).

Here is an example response body:

{
  "next-events" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/events?start=1272",
    "event": "1272"
  },
  "items" : [ {
    "id" : "1273",
    "type" : "task_start",
    "timestamp" : "2016-05-05T19:50:08Z",
    "details" : {
      "job-id" : "8765"
    }
  },
  {
    "id" : "1274",
    "type" : "plan_finished",
    "timestamp" : "2016-05-05T19:50:14Z",
    "details" : {
      "plan-id" : "1234",
      "result" : {
        "Plan output"
      },
    },
  }]
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:


Response code	Key	Description
`400`	`puppetlabs.orchestrator/validation-error`	The plan job ID or the `start` parameter in the request are not supplied as integers.
`404`	`puppetlabs.orchestrator/unknown-job`	No plan job exists that matches the specified plan job ID.

GET /plan_jobs/<job-id>/event/<event-id>

Retrieve the details of a specific event for a specific plan job.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include an integer plan job ID and an integer event ID. You can get plan job IDs from plan-related Command endpoints and the GET /plan_jobs endpoint. You can get event IDs from the GET /plan_jobs/<job-id>/events endpoint.

For example, this request queries event number 1272 for plan job number 352:

GET https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/event/1272

Tip: The URI path uses the singular event, and not events, like the GET /plan_jobs/<job-id>/events endpoint.

Response format

A successful response is a JSON object that uses these keys to provide the event details:


Key	Definition
`id`	The event's ID.
`type`	The event's type, determined by the event's status or circumstances that cause it to occur: `task_start`: A task run started. `script_start`: A script run starts as part of a plan. `command_start`: A command run starts as part of a plan. `upload_start`: A file upload starts as part of a plan. `wait_start`: A `wait_until_available()` call starts as part of a plan. `out_message`: As part of a plan, `out::message` is called. `apply_start`: A `puppet apply` run started as part of a plan. `apply_prep_start`: An `apply_prep` run starts as part of a plan. `plan_finished`: The plan job successfully finished. `plan_failed`: The plan job failed. A plan containing the `run_plan()` function completes the secondary plan during the primary plan job. Such subplans do not have their own plan jobs – They are included with, and completed as part of, the original job. These event types indicate when a subplan started or finished: `plan_start`: The `run_plan()` function started a plan within the current plan job. `plan_end`: The subplan, triggered by the `run_plan()` function, finished. This event type is specific to subplans and different from `plan_finished`.
`timestamp`	The time the event occurred (or was created).
`details`	A JSON object containing information about the event. Specific contents depends on the event type: For any `*_start` events (except `plan_start`), details include the `job-id` of the associated action or task. For `plan_finished` and `plan_failed` events, details include the `plan-id` and `result`. For `out_message` events, details include the complete `message` contents. For `plan_start` events, details include the `plan`, which identifies the subplan that ran within the original plan. For `plan_end` events, detail include the `plan` (which is the subplan that ran within the original plan) and the `duration` (which is how long the subplan ran).

Here is an example of a response body:

{    
    "id": "1265",
    "type": "out_message",
    "timestamp": "2016-05-05T19:50:06Z",
    "details": {
        "message": "this is an output message"
    }
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:


Response code	Key	Description
`400`	`puppetlabs.orchestrator/validation-error`	The plan job ID or the event ID in the request are not supplied as integers.
`404`	`puppetlabs.orchestrator/unknown-job`	No plan job exists that matches the specified plan job ID.
`404`	`puppetlabs.orchestrator/mismatched-job-event-id`	The specified event ID does not match any event ID associated with the specified plan job ID.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.