Jobs endpoints

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.

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

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"

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": {}
}

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.

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

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

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.

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.

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

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

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 ..."
  }]
}

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.