Skip to main contentIBM Quantum Documentation

Jobs

List user jobs

List user jobs

Query Parameters

Name, TypeDescription
provider
string

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

pending
boolean

Filters only pending or non pending jobs

backend
string

Comma separated systems to filter jobs

sort
string

Sort jobs by created time

Possible Values: ASCDESC
Default Value: DESC
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

createdAfter
string

Job created after filter

createdBefore
string

Job created before filter

tags
string[]

Tags to filter jobs

program
string

Program ID to filter jobs

sessionId
string

Session ID to filter jobs

composerOnly
boolean

Returns composer jobs only

Default Value: false
composerFile
string

Composer file name to filter jobs

search
string

Searches for jobs containing the specified keyword in their id, name or tags

HTTP Response Status Codes

Status codeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden

Code samples

GET
/facade/v1/jobs
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

{
  "jobs": [
    {
      "id": "c5dge2d3rn7breq27i9g",
      "hub": "ibm-q",
      "group": "open",
      "project": "main",
      "backend": "ibm_brisbane",
      "status": "Completed",
      "created": "2021-10-04T13:52:09.456851Z",
      "type": "RUNTIME",
      "tags": [
        "tag1",
        "tag2"
      ],
      "name": "",
      "runMode": "",
      "private": false,
      "endTime": "2021-10-04T13:54:09.456851Z",
      "state": {
        "status": "Completed",
        "reason": ""
      },
      "program": {
        "id": "myprogram-abcdef12345"
      },
      "runtime": "ntc-provider-primitives:latest",
      "sessionId": "123"
    }
  ],
  "count": 1,
  "limit": 1,
  "offset": 0
}

List tags

List tags containing the search keyword from all the user jobs

Query Parameters

Name, TypeDescription
search
Required
string

Lists job tags containing the keyword

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

HTTP Response Status Codes

Status codeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden

Code samples

GET
/facade/v1/jobs/tags
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs/tags \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

{
  "tags": [
    "tag1",
    "tag2",
    "tag3"
  ],
  "count": 3,
  "limit": 10,
  "offset": 0
}

Get job type

Get job type

Path Parameters

Name, TypeDescription
jobId
Required
string

Job ID

HTTP Response Status Codes

Status codeDescription
200OK
400Bad Request
401Unauthorized
403Forbidden

Code samples

GET
/facade/v1/jobs/{jobId}/type
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/facade/v1/jobs/{jobId}/type \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

{
  "id": "c5dge2d3rn7breq27i9g",
  "type": "RUNTIME"
}

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.

Body Parameters (application/json)

Name, TypeDescription
program_id
Required
string

ID of the primitive to be executed

hub
Required
string

The hub of the instance

group
Required
string

The group of the instance

project
Required
string

The project of the instance

backend
Required
string

Name that identifies the system 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. Should follow the pattern "name:tag".

log_level
string

Logging level of the job

Possible Values: criticalerrorwarninginfodebug
session_id
string

Identifier of the session that the job is a part of

tags
string[]

List of job tags

cost
number

Cost of the job as the estimated time it should take to complete (in seconds). Should not exceed the cost of the primitive

session_time
number

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.

HTTP Response Status Codes

Status codeDescription
200Returns the created job
400Bad request
401Unauthorized
403Forbidden
409Conflict
500Internal server error

Code samples

POST
/jobs
curl -X POST \
  https://api.quantum-computing.ibm.com/runtime/jobs \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"program_id":"circuit_runner","hub":"ibm-q","group":"open","project":"main","backend":"ibmq_wellington","params":{},"runtime":"runtime:1213","log_level":"INFO","session_id":"ccpm8gumg4jqer5oela0","tags":["job-1"],"cost":450,"session_time":1000}'

Responses

{
  "id": "ci8fo2g4mgo3p0c53uc0",
  "backend": "ibmq_toronto",
  "session_id": "ci8fo2g4mgo3p0c53uc0",
  "messages": [
    {
      "level": "warn",
      "data": "Your current pending jobs are estimated to consume 200 quantum seconds, but you only have 100 quantum seconds left in your monthly quota; therefore, it is likely this job will be canceled"
    }
  ]
}

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

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

program
string

Program ID to filter jobs

backend
string

System 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 -X GET \
  https://api.quantum-computing.ibm.com/runtime/jobs \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

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

Get job

Get 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
200Returns the job details
401Unauthorized
404Not found
500Internal server error

Code samples

GET
/jobs/{id}
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/jobs/{id} \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

{
  "id": "ch8b1ok4k9li68vm059r",
  "hub": "ibmq",
  "group": "open",
  "project": "main",
  "backend": "ibm_seattle",
  "state": {
    "status": "Cancelled",
    "reason": "Ran too long"
  },
  "status": "Cancelled",
  "params": {},
  "program": {
    "id": "ch8b1ok4k9li68vm059r"
  },
  "created": "2021-05-05 00:56:04.569709",
  "ended": "2021-05-05 00:56:04.569709",
  "runtime": "example",
  "cost": 1,
  "tags": [
    "test-job"
  ],
  "session_id": "ch8b1ok4k9li68vm059r",
  "usage": {
    "seconds": 1.5
  },
  "estimated_running_time_seconds": 123,
  "estimated_max_running_time_seconds": 123
}

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 \
  https://api.quantum-computing.ibm.com/runtime/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

Identifier of an existing job

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 \
  https://api.quantum-computing.ibm.com/runtime/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

Identifier of an existing job

HTTP Response Status Codes

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

Code samples

GET
/jobs/{id}/interim_results
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/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

Identifier of an existing job

HTTP Response Status Codes

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

Code samples

GET
/jobs/{id}/logs
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/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

Identifier of an existing job

HTTP Response Status Codes

Status codeDescription
200OK
401Unauthorized
403Forbidden
404Not Found

Code samples

GET
/jobs/{id}/metrics
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/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
}

Get job results

Return the final result from this job.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an existing job

HTTP Response Status Codes

Status codeDescription
200Return the job results
204The job exists but there is no result
401Unauthorized
404Not found
500Internal server error

Code samples

GET
/jobs/{id}/results
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/jobs/{id}/results \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

"example"

Replace job tags

Replace job tags

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an existing job

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 \
  https://api.quantum-computing.ibm.com/runtime/jobs/{id}/tags \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"Tags":["string"]}'

Responses

OK

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

Identifier of an existing job

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 -X GET \
  https://api.quantum-computing.ibm.com/runtime/jobs/{id}/transpiled_circuits \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

{
  "url": "https://quantum.ibm.com/transpiled-circuit/url"
}

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 -X GET \
  https://api.quantum-computing.ibm.com/runtime/stream/jobs \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

WebSocket stream

Get the job results stream

Get a result stream as the job runs.

Path Parameters

Name, TypeDescription
id
Required
string

Identifier of an existing job

HTTP Response Status Codes

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

Code samples

GET
/stream/jobs/{id}
curl -X GET \
  https://api.quantum-computing.ibm.com/runtime/stream/jobs/{id} \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Accept: application/json'

Responses

WebSocket stream
Was this page helpful?
Report a bug or request content on GitHub.