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.

Qiskit Runtime REST API

The Qiskit Runtime REST API allows you to run on quantum processing units (QPUs) using Qiskit Runtime primitives, a simplified interface for circuit execution powered by advanced runtime compilation, error suppression, and error mitigation techniques, as well as getting information about instances and QPUs you have access to.

Authentication

You must provide an IBM Cloud Identity and Access Management (IAM) bearer token with every call as an http header. You can generate this using your API key from the Dashboard, near the top for easy access. See the IAM Identity Services API for more information about bearer tokens. To generate one using the IAM REST API, you can use the following curl request.

curl -X POST 'https://iam.cloud.ibm.com/identity/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'

Expected Response

{
   "access_token": "<NEW_BEARER_TOKEN>",
   "refresh_token": "not_supported",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1473188353,
   "scope": "ibm_openid"
}
What is a bearer token?

A bearer token is a temporary credential that expires after no more than one hour. After the acquired token expires, you must generate a new one to continue calling IBM Cloud or other service APIs. You can only perform actions that are allowed by your level of assigned access within all accounts.

Use the response property expires_in in the API response to identify the length of time that your specific access token is valid.

Additionally, many requests to the REST API require an instance's Cloud Resource Name (CRN) in the request's header. You can see the instances you have access to on the dashboard, or by selecting the Instances page in the top-left menu. Each instance is listed with its CRN identifier.

Then, submit your bearer token and CRN on every request within an Authorization and Service-CRN header with this format:

Authorization: Bearer <YOUR_BEARER_TOKEN>
Service-CRN: <YOUR_INSTANCE_CRN>

Example request:

curl -X 'GET' \
    'https://quantum.cloud.ibm.com/api/v1/backends' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -H 'Service-CRN: <YOUR_INSTANCE_CRN>'

Submit a job

Note the following when submitting a job:

  • Use the create job operation to submit primitive jobs.
  • You can submit several circuits into a single job as an array of OpenQASM strings representing these circuits.
  • Specify the primitive you want to use with the program_id parameter. Available primitive values are sampler and estimator.
  • When submitting a job to a QPU, you need to specify the instance; for example, ibm-q/open/main. The API specifies this in three parameters: hub, group, and project, which are the substrings between / in your instance string.
  • For a list of the backend names you can specify, view the backends you have access to in the Compute resources section of IBM Quantum Platform.

Example request creating an estimator job with one circuit and one observable:

curl -X 'POST' \
  'https://quantum.cloud.ibm.com/api/v1/jobs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "estimator",
  "backend": "ibm_brisbane",
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;", "Z"
    ]],
    "options": {"dynamical_decoupling": {"enable": true}},
    "version": 2,
    "resilience_level": 1
  }
}'

Use sessions

To start a session, use the create session operation. The response provides an "id" that you can send with your jobs to run them as part of the session.

The next example creates a session (with no mode specified):

curl -X POST \
  'https://quantum.cloud.ibm.com/api/v1/sessions' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "mode": "dedicated",
  "max_ttl": 28800
}'

You will get a response like this:

{
  "id": "session_id1"
}

In your next job, use the session id to run this job as part of the session:

curl -X POST \
  'https://quantum.cloud.ibm.com/api/v1/jobs' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Service-CRN: <YOUR_INSTANCE_CRN>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "sampler",
  "backend": "ibm_brisbane",
  "session_id": "session_id1",
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;"
    ]],
    "options": {},
    "version": 2
  }
}'
Was this page helpful?
Report a bug or request content on GitHub.