Jobs endpoints

Use the jobs endpoints to examine jobs and their details.

You can:

For details about plan jobs, use the Plan jobs endpoints.

GET /jobs

Retrieve details about all 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/jobs?limit=20&offset=20
These parameters are available:
Parameter Definition
limit Set the maximum number of 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.
type Specify a job type to query, either deploy, task, or plan_task.
task Specify a task name to match. Partial matches are supported. If you specified type=deploy, you can't use task.
min_finish_timestamp Returns only the jobs that finished at or after the supplied UTC timestamp.
max_finish_timestamp Returns only the 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 job. Each object uses these keys to provide job details:
Key Definition
id An absolute URL that links to the newly created job.
name A stringified number identifying the newly created job. You can use this with other endpoints, such as GET /jobs/<job-id> (retrieve information about the status of the job) and POST /command/stop.
state The job's current state: new, ready, running, stopping, stopped, finished, or failed
Tip: If you want to know when a job entered and exited each state, use the GET /jobs/<job-id> endpoint.
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 (based 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, login, and other details 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.
node_states A JSON map containing the number of nodes involved with the job categorized by current node state. States with no nodes are omitted. If there were no nodes associated with the job, this value is null.
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.
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, offset, order_by, order, and type: 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 jobs and pagination information:
{
  "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1234",
      "name": "1234",
      "state": "finished",
      "command": "deploy",
      "type": "deploy",
      "node_count": 5,
      "node_states": {
        "finished": 2,
        "errored": 1,
        "failed": 1,
        "running": 1
      },
      "options": {
        "concurrency": null,
        "noop": false,
        "trace": false,
        "debug": false,
        "scope": {},
        "enforce_environment": true,
        "environment": "production",
        "evaltrace": false,
        "target": null,
        "description": "deploy the web app"
      },
      "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"
      },
      "report": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/report"
      },
      "events": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/events"
      },
      "nodes": {
        "id": "https://localhost:8143/orchestrator/v1/jobs/375/nodes"
      },
      "userdata": {
        "servicenow_ticket": "INC0011211"
      }
    },
    {
      "description": "",
      "report": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/report"
      },
      "name": "1235",
      "events": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/events"
      },
      "command": "plan_task",
      "type": "plan_task",
      "state": "finished",
      "nodes": {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235/nodes"
      },
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/1235",
      "environment": {
        "name": ""
      },
      "options": {
        "description": "",
        "plan_job": 197,
        "noop": null,
        "task": "facts",
        "sensitive": [],
        "scheduled-job-id": null,
        "params": {},
        "scope": {
          "nodes": [
            "orchestrator.example.com"
          ]
        },
        "project": {
          "project_id": "foo_id",
          "ref": "524df30f58002d30a3549c52c34a1cce29da2981"
        }
      },
      "timestamp": "2020-09-14T18:00:12Z",
      "started_timestamp":  "2020-09-14T17:59:05Z",
      "finished_timestamp":  "2020-09-14T18:00:12Z",
      "duration": "67.34",
      "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
      },
      "node_count": 1,
      "node_states": {
        "finished": 1
      },
      "userdata": {}
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "order": "asc",
    "order_by": "timestamp",
    "total": 2,
    "type": ""
  }
}

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 /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" GET "$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
Tip: 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.
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.

GET /jobs/<job-id>/nodes

Retrieve information about nodes associated with a specific job.

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. Job IDs are returned in responses from some Command endpoints and GET /jobs.

You can also append these optional parameters:
Key Definition
limit Set the maximum number of nodes to include in the response. The point at which the limit count starts is determined by offset, and the node 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 nodes starting with the 13th record. The default is 0.
order_by Specify one of the following categories to use to sort the results: name, duration, state, start_timestamp, or finish_timestamp.
order Indicate whether results are returned in ascending (asc) or descending (desc) order. The default is asc.
state Specify a specific node state to query: new, ready, running, stopping, stopped, finished, or failed.
For example, this URI queries up to 20 nodes in failed status:
https://orchestrator.example.com:8143/orchestrator/v1/jobs/375/nodes?limit=20&state=failed

Response format

The response is a JSON object containing an object, called next-events, and an array, called items.

The next-events object contains these keys:
  • id: A URI path you can use with the GET /jobs/<job-id>/events endpoint to get information about events associated with the job specified in the request.
  • event: An event ID.
The items array contains a JSON object for each node associated with the job. Each object uses these keys to provide node details:
Key Definition
timestamp The time of the most recent activity on the node. This is deprecated; use start_timestamp and finish_timestamp instead.
start_timestamp The time the node starting running. If the node hasn't started running, or if it was skipped, the value is nil.
finish_timestamp The time the node finished running. If the node hasn't finished running, or if it was skipped, the value is nil.
duration
  • If the node has finished running, this value is the duration, in seconds, of the Puppet run.
  • If the node is currently running, this value is the time, in seconds, that has elapsed since the node started running.
  • If the node hasn't started or was skipped, the value is nil.
state The node's current state.
transaction_uuid The ID of the nodes last report. This field is deprecated.
name The node's hostname.
details A JSON object containing a message and other information about the node's last event and the node's current state. It can be empty, and it might duplicate information from the results for historical reasons. For example:
  • If the node's state is finished or failed, the details include a report-url.
  • If the node's state is errored or skipped, check the message for information about the problem.
  • If the node's state is running, the details include the run-time in seconds.
result A JSON object describing the outcome and event information from the last node run. Exact contents depends on the job type (task job or a Puppet run) and whether the run succeeded, failed, or encountered an error. The node run must have ended to report results. For a task job, the results reflect the outcome of executing the task. For a Puppet run, the results reflect metrics from the Puppet run.
For example, this response describes one node:
{
  "next-events": {
    "id": "https://orchestrator.example.com:8143/orchestrator/v1/jobs/3/events?start=10",
    "event": "10"
  },
  "items" : [ {
    "timestamp" : "2015-07-13T20:37:01Z",
    "start_timestamp" : "2015-07-13T20:36:13Z",
    "finish_timestamp" : "2015-07-13T20:37:01Z",
    "duration" : 48.0,
    "state" : "finished",
    "transaction_uuid" : <UUID>,
    "name" : "node1.example.com",
    "details" : {
      "message": "Message from latest event"
    },
    "result": {
      "output_1": "success",
      "output_2": [1, 1, 2, 3,]
    }
  } ]
}
Here are some examples of various results objects:
Errors when running tasks
"result" : {
  "msg" : "Running tasks is not supported for agents older than version 5.1.0",
  "kind" : "puppetlabs.orchestrator/execution-failure",
  "details" : {
    "node" : "copper-6"
   }
}
"result" : {
  "error" : "Invalid task name 'package::status'"
}
Raw, standard task run output
"result" : {
  "output" : "test\n"
}
Structured task run output
"result" : {
  "status" : "up to date",
  "version" : "5.0.0.201.g879fc5a-1.el7"
}
Puppet run results
"result" : {
  "hash" : "d7ec44e176bb4b2e8a816157ebbae23b065b68cc",
  "noop" : {
    "noop" : false,
    "no_noop" : false
  },
  "status" : "unchanged",
  "metrics" : {
    "corrective_change" : 0,
    "out_of_sync" : 0,
    "restarted" : 0,
    "skipped" : 0,
    "total" : 347,
    "changed" : 0,
    "scheduled" : 0,
    "failed_to_restart" : 0,
    "failed" : 0
  },
  "environment" : "production",
  "configuration_version" : "1502024081"
}
puppet-apply ran as part of a plan
"result" : {
  "noop": false,
  "status" : "unchanged",
  "metrics" : {
    "corrective_change" : 0,
    "out_of_sync" : 0,
    "restarted" : 0,
    "skipped" : 0,
    "total" : 347,
    "changed" : 0,
    "scheduled" : 0,
    "failed_to_restart" : 0,
    "failed" : 0
  }
}

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.

GET /jobs/<job-id>/report

Returns a report that summarizes a specific job.

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/report
Job IDs are returned in responses from some Command endpoints and GET /jobs.

Response format

The response is a JSON object containing an array called items. The array contains one or more JSON objects summarizing the job's status on each node it ran (or is currently running) on. These keys are used:
Key Definition
node The hostname of a node that the job ran on.
state The job's current state on a specific node: new, ready, running, stopping, stopped, finished, or failed
timestamp The time when the job's state last changed.
events IDs of events associated with the particular job and node.
For example, this response contains one summary report:
{
  "items" : [ {
    "node" : "node1.example.com",
    "state" : "running",
    "timestamp" : "2015-07-13T20:37:01Z",
    "events" : [ ]
  }, {
  ...
  } ]
}

If you want more details about the job, use the GET /jobs/<job-id> endpoint.

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.

GET /jobs/<job-id>/events

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

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. Job IDs are returned in responses from some Command endpoints and GET /jobs.

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 job, starting with event number 1272:
GET https://orchestrator.example.com:8143/orchestrator/v1/jobs/352/events?start=1272

Response format

A successful response is a JSON object that uses these keys to detail the events in the job:
Key Definition
next-events Contains the id subkey, which has the URI supplied in the request as its value.
id An event's ID.
items An array of JSON objects where each object is an event.
type Each event has one event type, determined by the event's status or circumstances that cause it to occur:
  • node_errored: There was an error running Puppet on a node.
  • node_failed: The Puppet run failed.
  • node_finished: Puppet ran successfully.
  • node_running: Puppet has started running on a node.
  • node_skipped: A Puppet run was skipped on a node (for example, when a dependency fails).
  • job_aborted: A job ended without completing.
  • job_stopping: The job received a stop request, but it is still running (in the process of stopping).
  • job_finished: The job is no longer running. The details describe the final outcome. In the absence of errors, job_finished is always the last event for any job.
timestamp The time when the event was created.
details A JSON object containing information about the event.
message A message about the event.
Here is an example response body:
{
  "next-events" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/jobs/352/events?start=1272"
  },
  "items" : [ {
    "id" : "1272",
    "type" : "node_running",
    "timestamp" : "2016-05-05T19:50:08Z",
    "details" : {
      "node" : "puppet-agent.example.com",
      "detail" : {
        "noop" : false
      }
    },
    "message" : "Started puppet run on puppet-agent.example.com ..."
  }]
}

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 or the start parameter in the request are not supplied as integers.
404 puppetlabs.orchestrator/unknown-job No job exists that matches the specified job ID.