Plan jobs endpoints

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

You can:

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: 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: 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

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.

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.