GET /jobs/<job-id>

Retrieve details of a specific 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 task or deployment. For example, this request queries a job with ID 375:

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

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

A complete request might look like:

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

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

Response format

The response is a JSON object that uses these keys to provide job details:

Key Definition
id The URI path from the request.
name A stringified number identifying the job.
state The job's current state: new, ready, running, stopping, stopped, finished, or failed
The status key shows when the job entered and exited each state.
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 (specific options depend 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 and login 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.
I'm not sure if this endpoint reports node_states
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.
status The start and end times for each state the job was in.
userdata An object of arbitrary key/value data supplied to the job.

Here is an example response:

{
  "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
  "name" : "1234",
  "command" : "deploy",
  "type": "deploy",
  "state": "finished",
  "options" : {
    "concurrency" : null,
    "noop" : false,
    "trace" : false,
    "debug" : false,
    "scope" : {
      "nodes" : ["node1.example.com", "node2.example.com"] },
    "enforce_environment" : true,
    "environment" : "production",
    "evaltrace" : false,
    "target" : null
  },
  "node_count" : 2,
  "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"
  },
  "status" : [ {
    "state" : "new",
    "enter_time" : "2016-04-11T18:44:31Z",
    "exit_time" : "2016-04-11T18:44:31Z"
  }, {
    "state" : "ready",
    "enter_time" : "2016-04-11T18:44:31Z",
    "exit_time" : "2016-04-11T18:44:31Z"
  }, {
    "state" : "running",
    "enter_time" : "2016-04-11T18:44:31Z",
    "exit_time" : "2016-04-11T18:45:31Z"
  }, {
    "state" : "finished",
    "enter_time" : "2016-04-11T18:45:31Z",
    "exit_time" : null
  } ],
  "nodes" : { "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234/nodes" },
  "report" : { "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234/report" },
  "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 job exists that matches the specified job ID.