Workloads

List user instance workloads

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access

quantum-computing.workload.list

Auditing

Calling this method generates the following auditing events.

quantum-computing.workload.list

Query Parameters

Name, Type	Description
user string	User identifier. For now it can only be "me". Possible values: `me` Example: `"me"`
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
400	Bad request
401	Unauthorized

Code samples

GET

/v1/workloads

curl -X GET \
  /api/v1/workloads \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

import requests
 
response = requests.request(
    "GET",
    "/api/v1/workloads",
    headers={
      "Accept": "application/json",
      "IBM-API-Version": "2025-05-01",
      "Authorization": "Bearer YOUR-TOKEN",
      "Service-CRN": "YOUR-SERVICE-CRN"
    },
)
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,
      "estimated_running_time_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
          },
          "estimated_running_time_seconds": {
            "type": "number",
            "description": "Estimated usage in seconds",
            "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"
  ]
}