Skip to main content
IBM Quantum Platform

Jobs

Run a job

Invoke a Qiskit Runtime primitive. Note the returned job ID. You will use it to check the job's status and review results. This request is rate limited to 5 jobs per minute per user.

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.job.create

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.create

Input

Body Parameters
Name, Type
Description
program_id
string

ID of the program to be executed

backend
string

Name that identifies the backend on which to run the program.

runtime
string

Name and tag of the image to use when running a program (IBM Quantum channel users only). Should follow the pattern "name:tag".

tags
string[]

List of job or program tags

log_level
string

Logging level of the program

Possible values: criticalerrorwarninginfodebug
cost
integer

Cost of the job as the estimated time it should take to complete (in seconds). Should not exceed the cost of the program. If the provided value exceeds the maximum, it will be capped at that value.

Minimum value: 0
Maximum value: 10800
session_id
string

Identifier of the session that the job is a part of

calibration_id
string

The ID of the calibration used for the job

params
private
boolean

When set to true, input parameters are not returned, and the results can only be read once. After the job is completed, input parameters are deleted from the service. After the results are read, they are deleted from the service. When set to false, the input parameters and results follow the standard retention behavior of the API. Only returned in the response if the value is true, otherwise it is omitted.

Code samples
POST
/v1/jobs

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

curl -X POST \
  https://quantum.cloud.ibm.com/api/v1/jobs \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Usage exceeds instance limit
Responses
{
  "id": "c5dge2d3rn7breq27i9g",
  "backend": "ibm_backend",
  "private": true
}

List jobs

List the quantum program jobs you have run.

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.job.read

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.read

Input

Query Parameters
Name, Type
Description
limit
integer

Number of results to return at a time. If the provided value is outside of the viable range, no error occurs and the default value is used instead.

Default value: 200
Minimum value: 1
Maximum value: 200
offset
integer

Number of results to offset when retrieving the list of jobs. If the provided value is outside of the viable range, no error occurs and the default value is used instead.

Default value: 0
Minimum value: 0
Maximum value: 2147483647
pending
boolean

Returns 'Queued' and 'Running' jobs if true. Returns 'Completed', 'Cancelled', and 'Failed' jobs if false.

program
string

Program ID to filter jobs

backend
string

Backend to filter jobs

created_after
string

Job created after filter

created_before
string

Job created before filter

sort
string

Sort jobs by created time ASC or DESC (default)

tags
string[]

Tags to filter jobs

session_id
string

Session ID to filter jobs

exclude_params
boolean

Exclude job params from the response

Default value: true
Code samples
GET
/v1/jobs

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

curl -X GET \
  https://quantum.cloud.ibm.com/api/v1/jobs \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
Responses
{
  "jobs": [
    {
      "id": "c5dge2d3rn7breq27i9g",
      "backend": "ibmq_qasm_simulator",
      "cost": 0,
      "state": {
        "status": "Completed",
        "reason": ""
      },
      "status": "Completed",
      "params": {
        "iterations": 3
      },
      "program": {
        "id": "myprogram-abcdef12345"
      },
      "created": "2021-10-04T13:52:09.456851Z",
      "runtime": "ntc-provider-primitives:latest",
      "tags": [
        "tag1",
        "tag2",
        "tag3",
        "tag4"
      ],
      "session_id": "c5dge2d3rn7breq27i9g",
      "usage": {
        "seconds": 1
      },
      "private": true,
      "estimated_running_time_seconds": 30.5,
      "calibration_id": "fez-ac-tls-test"
    },
    {
      "id": "c2gfe1m3ln7breq27i6e",
      "backend": "ibmq_qasm_simulator",
      "cost": 0,
      "state": {
        "status": "Completed",
        "reason": ""
      },
      "status": "Completed",
      "params": {
        "iterations": 3
      },
      "program": {
        "id": "myprogram-abcdef12345"
      },
      "created": "2021-10-05T13:52:09.456851Z",
      "runtime": "ntc-provider-primitives:latest",
      "tags": [
        "tag1",
        "tag2",
        "tag3",
        "tag4"
      ],
      "session_id": "c1mre2f3pn9breq18i4g",
      "usage": {
        "seconds": 1
      }
    }
  ],
  "count": 2,
  "limit": 2,
  "offset": 0
}

List job details

List the details about the specified quantum program job.

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.job.read

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.read

Input

Path Parameters
Name, Type
Description
id
Required
string

Identifier of an existing job

Query Parameters
Name, Type
Description
exclude_params
boolean

Exclude job params from the response

Default value: false
Code samples
GET
/v1/jobs/{id}

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs/{id}

curl -X GET \
  https://quantum.cloud.ibm.com/api/v1/jobs/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
200OK
401Unauthorized
403Forbidden
404Not Found
Responses
{
  "id": "c5dge2d3rn7breq27i9g",
  "backend": "ibmq_qasm_simulator",
  "cost": 0,
  "state": {
    "status": "Completed",
    "reason": ""
  },
  "status": "Completed",
  "params": {
    "iterations": 3
  },
  "program": {
    "id": "myprogram-abcdef12345"
  },
  "created": "2021-10-04T13:52:09.456851Z",
  "runtime": "ntc-provider-primitives:latest",
  "tags": [
    "tag1",
    "tag2",
    "tag3",
    "tag4"
  ],
  "session_id": "c5dge2d3rn7breq27i9g",
  "private": true,
  "estimated_running_time_seconds": 30.5,
  "calibration_id": "fez-ac-tls-test"
}

Delete a job

Delete the specified job and its associated data. Job must be in a terminal state.

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.job.delete

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.delete

Input

Path Parameters
Name, Type
Description
id
Required
string

Identifier of an existing job

Code samples
DELETE
/v1/jobs/{id}

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs/{id}

curl -X DELETE \
  https://quantum.cloud.ibm.com/api/v1/jobs/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
204OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal error deleting job
Responses
OK

Cancel a job

Cancels the specified job.

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.job.cancel

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.cancel

Input

Path Parameters
Name, Type
Description
id
Required
string

A job ID

Code samples
POST
/v1/jobs/{id}/cancel

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs/{id}/cancel

curl -X POST \
  https://quantum.cloud.ibm.com/api/v1/jobs/{id}/cancel \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
204OK
400Bad cancel request
401Unauthorized
403Forbidden
404Not Found
409Job is in non cancellable status.
500Internal error cancelling job
Responses
OK

List job logs

List all job logs for the specified job.

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.job.read

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.read

Input

Path Parameters
Name, Type
Description
id
Required
string

A job ID

Code samples
GET
/v1/jobs/{id}/logs

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs/{id}/logs

curl -X GET \
  https://quantum.cloud.ibm.com/api/v1/jobs/{id}/logs \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
200Returns job logs.
401Unauthorized
403Forbidden
404Not found
Responses
Returns job logs.

Get job metrics

Gets metrics of specified job

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.job.read

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.read

Input

Path Parameters
Name, Type
Description
id
Required
string

A job ID

Code samples
GET
/v1/jobs/{id}/metrics

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs/{id}/metrics

curl -X GET \
  https://quantum.cloud.ibm.com/api/v1/jobs/{id}/metrics \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
200OK
401Unauthorized
403Forbidden
404Not Found
Responses
{
  "timestamps": {
    "created": "2022-06-20T12:55:20.268427Z",
    "running": "2022-06-20T12:55:20.268427Z",
    "finished": "2022-06-20T12:55:20.268427Z"
  },
  "bss": {
    "seconds": 123
  },
  "usage": {
    "quantum_seconds": 123,
    "seconds": 123
  },
  "executions": 123,
  "num_circuits": 123,
  "num_qubits": [
    1,
    2,
    3
  ],
  "circuit_depths": [
    0,
    1,
    2,
    3
  ],
  "qiskit_version": "0.36.2",
  "estimated_start_time": "2022-06-20T12:55:20.268427Z",
  "estimated_completion_time": "2022-06-20T12:55:20.268427Z",
  "position_in_queue": 10,
  "position_in_provider": 10
}

List job results

Return the final result from this job.

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.job.read

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.read

Input

Path Parameters
Name, Type
Description
id
Required
string

A job ID

Code samples
GET
/v1/jobs/{id}/results

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs/{id}/results

curl -X GET \
  https://quantum.cloud.ibm.com/api/v1/jobs/{id}/results \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15'

Output

HTTP Response Status Codes
Status code
Description
200Returns the job's final result.
204Job's final result not found.
400Bad Request
401Unauthorized
403Forbidden
404Not Found
Responses
Returns the job's final result.

Replace job tags

Replace job tags

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.job.update

Auditing

Calling this method generates the following auditing events.

  • quantum-computing.job.update

Input

Path Parameters
Name, Type
Description
id
Required
string

A job ID

Body Parameters
Name, Type
Description
tags
Required
string[]

List of job or program tags

Code samples
PUT
/v1/jobs/{id}/tags

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs/{id}/tags

curl -X PUT \
  https://quantum.cloud.ibm.com/api/v1/jobs/{id}/tags \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2026-02-15' \
  -H 'Content-Type: application/json' \
  -d '{"tags":["example"]}'

Output

HTTP Response Status Codes
Status code
Description
204OK
401Unauthorized
403Forbidden
404Not Found
Responses
OK
Was this page helpful?
Report a bug, typo, or request content on GitHub.