Retrieve a list of jobs

GET api/jobs/

Retrieves a list of jobs. A table of job IDs is available in the SC//Reliant™ Platform Manager dashboard on the Remote Job Execution tab as well.

Request syntax

get api/jobs

Request parameters

The request accepts the following query parameters.

Parameter	Type	Description	Required	Default value
`page`	Integer	The page number to retrieve.	No	`1`
`page_size`	Integer	The number of results to return for each page.	No	`1000`
`status`	String	Filter the results by Job status. Available values are `in_progress`, `finished`, `failed`, `pending`, and `partially_failed`.	No	Null
`type`	String	Filter the results by Job type. Available values are `ExportersJob`, `ServiceCheckJob`, `RvcJob`, `Rvc3Job`, `PuppetJob`, `ETLImport`, `HierarchyImport`, `LocationImport`, `NodeImport`, `ServerImport`, and `StoreImport`.	No	Null
`location`	String	Filter the results by location.	No	Null
`include_payload`	Boolean	If `true`, the response includes the payload information.	No	`false`

Response syntax

{
    "page": integer,
    "page_size": integer,
    "pages_total": integer,
    "items_total": integer,
    "jobs": [
        {
            "id": integer,
            "type": "string",
            "status": "string",
            "message": "string",
            "process_time": integer,
            "username": "string",
            "payload": {},
            "created_at": "timestamp",
            "updated_at": "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
`page`	Integer	The page number of the results.
`page_size`	Integer	The maximum number of jobs on each page.
`pages_total`	Integer	The total number of pages for the filtered results.
`items_total`	Integer	The total number of jobs that match the filters.
`jobs`	Object array	The jobs on this page, newest first. Each job has the fields below.
`id`	Integer	The ID of the job. Use it to retrieve the job details, for example with `GET api/jobs/<id>?include_payload=true`.
`type`	String	The type of job, for example `Rvc3Job` or `PuppetJob`.
`status`	String	The status of the job.
`message`	String	This field is reserved for internal use.
`process_time`	Integer	How long the job took to process, in milliseconds.
`username`	String	The username of the person who initiated the job.
`payload`	Object	The results of the job. Only returned when `include_payload` is `true`.
`created_at`	Timestamp	When the job was created, in ISO 8601 UTC datetime format.
`updated_at`	Timestamp	When the job was last updated, in ISO 8601 UTC datetime format.

Errors

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

Code	Message	Cause
`400`	`Validation Failed: status does not have a valid value`	The `status` filter is not one of the available values.
`400`	`Validation Failed: type does not have a valid value`	The `type` filter is not one of the available values.
`404`	`Not found`	The location in the `location` filter does not exist.
`500`	`500 Internal Server Error`	`page_size` is `0`. Use a page size of at least `1`.

Examples

Example 1: Retrieve a list of jobs.

This example retrieves the two most recent jobs.

ruby api.rb <customer_code> GET "api/jobs?page_size=2"

Response

{
  "page": 1,
  "page_size": 2,
  "pages_total": 7759,
  "items_total": 15517,
  "jobs": [
    {
      "id": 1782416,
      "type": "Rvc3Job",
      "status": "finished",
      "message": null,
      "process_time": 595,
      "username": "test.user",
      "created_at": "2026-10-12T17:38:50.999Z",
      "updated_at": "2026-10-12T17:38:51.605Z"
    },
    {
      "id": 1782415,
      "type": "Rvc3Job",
      "status": "finished",
      "message": null,
      "process_time": 645,
      "username": "test.user",
      "created_at": "2026-10-12T17:38:41.939Z",
      "updated_at": "2026-10-12T17:38:42.627Z"
    }
  ]
}

Example 2: Retrieve a list of finished jobs of a specific type.

This example retrieves the two most recent finished jobs with type Rvc3Job.

ruby api.rb <customer_code> GET "api/jobs?status=finished&type=Rvc3Job&page_size=2"

Response

{
  "page": 1,
  "page_size": 2,
  "pages_total": 2020,
  "items_total": 4040,
  "jobs": [
    {
      "id": 1782416,
      "type": "Rvc3Job",
      "status": "finished",
      "message": null,
      "process_time": 595,
      "username": "test.user",
      "created_at": "2026-10-12T17:38:50.999Z",
      "updated_at": "2026-10-12T17:38:51.605Z"
    },
    {
      "id": 1782415,
      "type": "Rvc3Job",
      "status": "finished",
      "message": null,
      "process_time": 645,
      "username": "test.user",
      "created_at": "2026-10-12T17:38:41.939Z",
      "updated_at": "2026-10-12T17:38:42.627Z"
    }
  ]
}

Example 3: Retrieve a job with its payload.

This example retrieves the most recent Puppet job, including its payload.

ruby api.rb <customer_code> GET "api/jobs?type=PuppetJob&page_size=1&include_payload=true"

Response

{
  "page": 1,
  "page_size": 1,
  "pages_total": 181,
  "items_total": 181,
  "jobs": [
    {
      "id": 1777046,
      "type": "PuppetJob",
      "status": "finished",
      "message": null,
      "process_time": 1457,
      "username": "test.user",
      "payload": {
        "success_nodes": {
          "sit0001red0": {
            "status": "Currently applying a catalog; last completed run 31 minutes 36 seconds ago"
          }
        }
      },
      "created_at": "2026-10-01T14:16:55.107Z",
      "updated_at": "2026-10-01T14:16:56.576Z"
    }
  ]
}