Retrieve details about a job

GET api/jobs/job-id

Retrieves details about an asynchronous job. This provides a way to uniformly retrieve information about initiated, running, and completed jobs. The job ID must be specified. A table of job IDs is available in the SC//Reliant™ Platform Manager dashboard on the Remote Job Execution tab.

Request syntax

get api/jobs/<job_id>

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required	Default value
`include_payload`	Boolean	If `true`, the response includes the payload information.	No	`false`

Response syntax

{
  "id": integer,
  "type": "string",
  "status": "string",
  "message": "string",
  "trigged_by": "string",
  "success_nodes_count": integer,
  "failed_nodes_count": integer,
  "total_nodes_count": integer,
  "parameters": {
    "action": "string",
    "hostnames": [
      "string",
      "string"
    ]
  },
  "time_started": "timestamp",
  "time_finished": "timestamp"
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

Field	Type	Description
`id`	Integer	The ID of the job.
`type`	String	The type of job. Examples of job types are `Puppet`, `RVC`, and `Service Check`.
`status`	String	The status of the job.
`message`	String	This field is reserved for internal use.
`trigged_by`	String	The username of the person who initiated the job.
`success_nodes_count`	Integer	The number of nodes that returned a successful response.
`failed_nodes_count`	Integer	The number of nodes that returned a failed response.
`total_nodes_count`	Integer	The total number of nodes the job ran on.
`parameters`	String	The details about the job request.
`time_started`	Timestamp	The timestamp indicating when the job started. The timestamp is given in ISO 8601 UTC datetime format.
`time_finished`	Timestamp	The timestamp indicating when the job finished. The timestamp is given in ISO 8601 UTC datetime format.

Errors

The following are common errors returned by this API. For a list of additional common errors, see Common errors.

Code	Message	Cause
404	`Not Found`	The requested job ID is invalid. Verify the job ID and try again.

Examples

Example 1: Retrieve details about a job.

This example retrieves details about job ID 1537458.

ruby api.rb <customer_code> get api/jobs/1537458

Response

{
  "id": 1537458,
  "type": "Puppet",
  "status": "finished",
  "message": null,
  "trigged_by": "test_user",
  "success_nodes_count": 2,
  "failed_nodes_count": 0,
  "total_nodes_count": 2,
  "parameters": {
    "action": "last_run_summary",
    "hostnames": [
      "sit0016red0",
      "sit0016red1"
    ]
  },
  "time_started": "2024-08-26T14:53:18Z",
  "time_finished": "2024-08-26T14:53:18Z"
}

Example 2: Retrieve details about a job that includes the payload.

This example retrieves details about job ID 1537458 and includes the payload in the response.

ruby api.rb <customer_code> get api/jobs/1537458\?include_payload=true

Response

{
    "id": 1537458,
    "type": "Puppet",
    "status": "finished",
    "message": null,
    "payload": {
        "success_nodes": {
            "sit0016red0": {
                "time": {
                    "total_time": "70.81790523300002 seconds",
                    "since_lastrun": "143 seconds",
                    "config_retrieval_time": "15.389175765 seconds"
                },
                "resources": {
                    "total_resources": 6282,
                    "failed_resources": 0,
                    "changed_resources": 26,
                    "skipped_resources": 0,
                    "corrected_resources": 5,
                    "out_of_sync_resources": 26
                }
            },
            "sit0016red1": {
                "time": {
                    "total_time": "95.20309409100003 seconds",
                    "since_lastrun": "57 seconds",
                    "config_retrieval_time": "19.270064261 seconds"
                },
                "resources": {
                    "total_resources": 6258,
                    "failed_resources": 0,
                    "changed_resources": 22,
                    "skipped_resources": 0,
                    "corrected_resources": 5,
                    "out_of_sync_resources": 22
                }
            }
        }
    },
    "trigged_by": "test.user",
    "success_nodes_count": 2,
    "failed_nodes_count": 0,
    "total_nodes_count": 2,
    "parameters": {
        "action": "last_run_summary",
        "hostnames": [
            "sit0016red0",
            "sit0016red1"
        ]
    },
    "time_started": "2024-08-26T14:53:18Z",
    "time_finished": "2024-08-26T14:53:18Z"
}