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

Body Parameters (application/json)

Name, TypeDescription
One of

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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

Query Parameters

Name, TypeDescription
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
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
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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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.

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

Path Parameters

Name, TypeDescription
id
Required
string

A job ID

HTTP Response Status Codes

Status codeDescription
200Returns job interim results.
204Empty interim results for private jobs.
401Unauthorized
403Forbidden
404Not Found

Code samples

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

Responses

Returns job interim results.

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01' \
  -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.

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

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 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-TOKEN' \
  -H 'Service-CRN: YOUR-SERVICE-CRN' \
  -H 'IBM-API-Version: 2025-05-01'

Responses

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