Skip to main contentIBM Quantum Documentation

Jobs

Endpoints related to running jobs


List jobs

List the quantum jobs you have run.

Query Parameters

Name, TypeDescription
limit
integer

Number of results to return at a time

Default Value: 200
offset
integer

Number of results to offset when retrieving the list of jobs

pending
boolean

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

provider
string

Provider to filter jobs. Should be in the following format {hub}/{group}/{project}

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[]

List of job or program tags

session_id
string

Session ID to filter jobs

exclude_params
boolean

Exclude job params from the response

Default Value: true

HTTP Response Status Codes

Status codeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found

Code samples

GET
/jobs
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs

Responses

{
  "jobs": [
    {
      "id": "c5dge2d3rn7breq27i9g",
      "backend": "ibmq_qasm_simulator",
      "state": {
        "status": "Completed",
        "reason": ""
      },
      "status": "Completed",
      "params": {
        "iterations": 3
      },
      "program": {
        "id": "sampler"
      },
      "created": "2021-10-04T13:52:09.456851Z",
      "runtime": "ntc-provider-primitives:latest",
      "tags": [
        "tag1",
        "tag2",
        "tag3",
        "tag4"
      ],
      "session_id": "c5dge2d3rn7breq27i9g",
      "usage": {
        "seconds": 1
      }
    }
  ],
  "count": 1,
  "limit": 1,
  "offset": 0
}

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.

Body Parameters (application/json)

Name, TypeDescription
program_id
Required
string

ID of the primitive to be executed

hub
string

Provider hub name (IBM Quantum users only)

group
string

Provider group name (IBM Quantum users only)

project
string

Provider project name (IBM Quantum users only)

backend
string

Name that identifies the backend on which to run the job

params
object

Parameters to inject into the primitive as key-value pairs

runtime
string

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

Tags
string[]

List of job or program tags

log_level
string

Logging level of the job

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 primitive

session_id
string

Identifier of the session that the job is a part of

start_session
boolean

Flag to start a new runtime session

Default Value: false
session_time
integer

Parameter to specify length of a session in seconds. A session allows to group a collection of iterative calls to the quantum computer. Session length cannot exceed user device limit and should be greater than job cost.

remote_storage

HTTP Response Status Codes

Status codeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Usage exceeds instance limit

Code samples

POST
/jobs
curl -X POST \
  -H "x-access-token: <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d {"program_id":"program_id"} \
  https://runtime-us-east.quantum-computing.ibm.com/jobs

Responses

{
  "id": "c5dge2d3rn7breq27i9g"
}

List job details

List the details about the specified quantum job.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an existing job

Query Parameters

Name, TypeDescription
exclude_params
boolean

Exclude job params from the response

Default Value: false

HTTP Response Status Codes

Status codeDescription
200OK
401Unauthorized
403Forbidden
404Not Found

Code samples

GET
/jobs/{id}
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}

Responses

{
  "id": "c5dge2d3rn7breq27i9g",
  "backend": "ibmq_qasm_simulator",
  "state": {
    "status": "Completed",
    "reason": ""
  },
  "status": "Completed",
  "params": {
    "iterations": 3
  },
  "program": {
    "id": "sampler"
  },
  "created": "2021-10-04T13:52:09.456851Z",
  "runtime": "ntc-provider-primitives:latest",
  "tags": [
    "tag1",
    "tag2",
    "tag3",
    "tag4"
  ],
  "session_id": "c5dge2d3rn7breq27i9g"
}

Delete a job

Delete the specified job.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an existing job

HTTP Response Status Codes

Status codeDescription
204OK
401Unauthorized
403Forbidden
404Not Found

Code samples

DELETE
/jobs/{id}
curl -X DELETE -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}

Responses

OK

List job results

Return the final result from this job.

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
200Returns the job's final result.
204Job's final result not found.
400Bad Request
401Unauthorized
403Forbidden
404Not Found

Code samples

GET
/jobs/{id}/results
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/results

Responses

Returns the job's final result.

List job interim results

Return the interim results from this job. Interim results are kept two days after the job has finished running.

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
200Returns job interim results.
401Unauthorized
403Forbidden
404Not Found

Code samples

GET
/jobs/{id}/interim_results
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/interim_results

Responses

Returns job interim results.

Get job transpiled circuits

Return a presigned download URL for the transpiled circuits. Currently supported only for the sampler primitive.

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
200Returns a presigned URL to download job transpiled circuits.
401Unauthorized
403Forbidden
404Not Found

Code samples

GET
/jobs/{id}/transpiled_circuits
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/transpiled_circuits

Responses

Returns a presigned URL to download job transpiled circuits.

List job logs

List all job logs for the specified job.

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
200Returns job logs.
401Unauthorized
403Forbidden
404Not found

Code samples

GET
/jobs/{id}/logs
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/logs

Responses

Returns job logs.

Cancel a job

Cancels the specified job.

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
204OK
401Unauthorized
403Forbidden
404Not Found
409Job is in non cancellable status.

Code samples

POST
/jobs/{id}/cancel
curl -X POST -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/cancel

Responses

OK

Get job metrics

Gets metrics of specified job

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
200OK
401Unauthorized
403Forbidden
404Not Found

Code samples

GET
/jobs/{id}/metrics
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/metrics

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
}

Replace job tags

Replace job tags

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

Body Parameters (application/json)

Name, TypeDescription
Tags
Required
string[]

List of job or program tags

HTTP Response Status Codes

Status codeDescription
204OK
401Unauthorized
403Forbidden
404Not Found

Code samples

PUT
/jobs/{id}/tags
curl -X PUT \
  -H "x-access-token: <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d {"tags":["tags","tags"]} \
  https://runtime-us-east.quantum-computing.ibm.com/jobs/{id}/tags

Responses

OK

Get the job results stream

Get a result stream as the job runs.

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
200WebSocket stream
303Found
401Unauthorized
500Internal error

Code samples

GET
/stream/jobs/{id}
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/stream/jobs/{id}

Responses

WebSocket stream

Get jobs state updates

Get jobs state updates

HTTP Response Status Codes

Status codeDescription
200WebSocket stream
303Found
401Unauthorized
500Internal error

Code samples

GET
/stream/jobs
curl -H "x-access-token: <YOUR-TOKEN>" \
  https://runtime-us-east.quantum-computing.ibm.com/stream/jobs

Responses

WebSocket stream
Was this page helpful?