Workloads

List user instance workloads

List user instance workloads

Query Parameters

Name, Type	Description
sort string	$Field to sort the workloads by. A - prefix indicates descending sort order.$ Possible values: `createdAt-createdAt` Default value: `createdAt`
limit number	$Number of workloads to return at a time$ Default value: `10` Example: `5`
previous string	$Cursor to previous workloads result page$
next string	$Cursor to next workloads result page$
backend string	$Backend name$ Example: `"ibm_seattle"`
search string	$Optional search string, used to filter workloads by id or tags$ Example: `"test"`
status string[]	$Status type to filter workloads by. It can be pending, in_progress, failed, completed or canceled.$ Example: `["pending"]`
mode string	$Workload mode: job, session or batch$ Possible values: `jobsessionbatch` Example: `"batch"`
created_after string	$Filter jobs and session created after this date$ Example: `"2021-01-01T00:00:00Z"`
created_before string	$Filter jobs and session created before this date$ Example: `"2021-01-01T00:00:00Z"`
tags string[]	$Optional array of tags for the workloads$ Example: `["composer-info:composer:true","bar","foo"]`

HTTP Response Status Codes

Status code	Description
200
401	Unauthorized

Code samples

GET

/v1/workloads

curl -X GET \
  /api/v1/workloads \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

import requests
 
response = requests.request(
    "GET",
    "/api/v1/workloads",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_API_TOKEN_HERE"
    },
)
print(response.json())

Responses

Status code

{
  "workloads": [
    {
      "id": "ch8b1ok4k9li68vm059r",
      "created": "2024-07-04T16:13:56.562Z",
      "ended": "2024-07-04T16:13:56.562Z",
      "backend": "ibm_seattle",
      "instance": "ibmq/open/main",
      "user_id": "65f0478ed32a1891af0a8d31",
      "accepting_jobs": true,
      "mode": "job",
      "status": "in_progress",
      "status_reason": "Error occurred for job circuit-runner_ckodgbs1fc4b8ufrjsd0_d35e_2. Stale payload, retry maximum reached.",
      "tags": [
        "test-job",
        "foo",
        "bar"
      ],
      "usage_seconds": 1
    }
  ],
  "total_count": 5,
  "limit": 5,
  "previous": {
    "href": "https://api.example.com/v2/accounts?previous=3fe78a36b9aa7f26"
  },
  "next": {
    "href": "https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26"
  }
}

Status code

{
  "type": "object",
  "properties": {
    "workloads": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Workload id (job and session id)",
            "example": "ch8b1ok4k9li68vm059r"
          },
          "created": {
            "type": "string",
            "description": "Creation date",
            "example": "2024-07-04T16:13:56.562Z"
          },
          "ended": {
            "type": "string",
            "description": "End date",
            "example": "2024-07-04T16:13:56.562Z"
          },
          "backend": {
            "type": "string",
            "description": "Backend name",
            "example": "ibm_seattle"
          },
          "instance": {
            "type": "string",
            "description": "Instance as hub/group/project",
            "example": "ibmq/open/main"
          },
          "user_id": {
            "type": "string",
            "description": "User id",
            "example": "65f0478ed32a1891af0a8d31"
          },
          "accepting_jobs": {
            "type": "boolean",
            "description": "true if the session accepts jobs, false otherwise. Only for sessions, null for jobs",
            "example": true,
            "nullable": true
          },
          "mode": {
            "type": "string",
            "description": "Workload mode: job, session or batch",
            "example": "job",
            "enum": [
              "job",
              "session",
              "batch"
            ]
          },
          "status": {
            "type": "string",
            "description": "State for the workload.",
            "example": "in_progress",
            "enum": [
              "completed",
              "canceled",
              "failed",
              "pending",
              "in_progress"
            ]
          },
          "status_reason": {
            "type": "string",
            "description": "Jobs only, status reason for the job",
            "example": "Error occurred for job circuit-runner_ckodgbs1fc4b8ufrjsd0_d35e_2. Stale payload, retry maximum reached."
          },
          "tags": {
            "description": "Tags for the jobs",
            "example": [
              "test-job",
              "foo",
              "bar"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "usage_seconds": {
            "type": "number",
            "description": "Usage in seconds. Can be null for ongoing workloads.",
            "example": 1
          }
        },
        "required": [
          "id",
          "created",
          "backend",
          "instance",
          "user_id",
          "mode",
          "status"
        ]
      }
    },
    "total_count": {
      "type": "number",
      "example": 5
    },
    "limit": {
      "type": "number",
      "example": 5
    },
    "previous": {
      "example": {
        "href": "https://api.example.com/v2/accounts?previous=3fe78a36b9aa7f26"
      },
      "allOf": [
        {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "example": [
                "https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26",
                "https://api.example.com/v2/accounts?previous=3fe78a36b9aa7f26"
              ]
            }
          }
        }
      ]
    },
    "next": {
      "example": {
        "href": "https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26"
      },
      "allOf": [
        {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "example": [
                "https://api.example.com/v2/accounts?next=3fe78a36b9aa7f26",
                "https://api.example.com/v2/accounts?previous=3fe78a36b9aa7f26"
              ]
            }
          }
        }
      ]
    }
  },
  "required": [
    "workloads",
    "total_count",
    "limit"
  ]
}