Skip to main content
IBM Quantum Platform
This is the API reference for the Qiskit Runtime REST API on the new IBM Quantum Platform, which replaces the REST APIs for IBM Quantum Platform (Classic) Qiskit Runtime and IBM Cloud Qiskit Runtime. For more details, including how to migrate, visit the guide Migrate to the new Qiskit Runtime REST API.

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.

Body Parameters (application/json)

Name, TypeDescription

HTTP Response Status Codes

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

Code samples

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

Responses

{
  "id": "c5dge2d3rn7breq27i9g",
  "backend": "ibm_backend"
}

List jobs

List the quantum program 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.

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

HTTP Response Status Codes

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

Code samples

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

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
      }
    }
  ],
  "count": 1,
  "limit": 1,
  "offset": 0
}

List job details

List the details about the specified quantum program 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
/v1/jobs/{id}
curl -X GET \
  /api/v1/jobs/{id} \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

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"
}

Delete a job

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

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an existing job

HTTP Response Status Codes

Status codeDescription
204OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal error deleting job

Code samples

DELETE
/v1/jobs/{id}
curl -X DELETE \
  /api/v1/jobs/{id} \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

OK

Cancel a job

Cancels the specified job.

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
204OK
400Bad cancel request
401Unauthorized
403Forbidden
404Not Found
409Job is in non cancellable status.
500Internal error cancelling job

Code samples

POST
/v1/jobs/{id}/cancel
curl -X POST \
  /api/v1/jobs/{id}/cancel \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

OK

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
/v1/jobs/{id}/interim_results
curl -X GET \
  /api/v1/jobs/{id}/interim_results \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

Returns job interim results.

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
/v1/jobs/{id}/logs
curl -X GET \
  /api/v1/jobs/{id}/logs \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

Returns job logs.

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
/v1/jobs/{id}/metrics
curl -X GET \
  /api/v1/jobs/{id}/metrics \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

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.

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
/v1/jobs/{id}/results
curl -X GET \
  /api/v1/jobs/{id}/results \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

Returns the job's final result.

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
/v1/jobs/{id}/tags
curl -X PUT \
  /api/v1/jobs/{id}/tags \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"tags":["example"]}'

Responses

OK

Get job transpiled circuits

Return a presigned download URL for the transpiled circuits. Currently supported only for 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
/v1/jobs/{id}/transpiled_circuits
curl -X GET \
  /api/v1/jobs/{id}/transpiled_circuits \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

{
  "url": "example"
}
Was this page helpful?
Report a bug or request content on GitHub.