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.