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.