Skip to main content
IBM Quantum Platform

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.

Manage instances with IBM Cloud Resource Controller API

Before using the Qiskit Runtime REST API, you need a Qiskit Runtime instance. You can create and manage instances in two ways:

The following sections describe the API approach for programmatic instance management, including setting allocation limits and backend access.

Instance parameters

When creating or updating a Qiskit Runtime instance via the IBM Cloud Resource Controller API, you can configure the following parameters in the request body:

  • instance_limit_seconds (optional): The limit to set on the instance (string or null). For Open Plan, defaults to 10 minutes if omitted.
  • usage_allocation_seconds: Allotted time for the instance (string or null), used by the fair-share scheduler to determine queue priority based on usage of all QPUs. Does not apply to Pay-As-You-Go instances.
  • backends: Array of backend names available to this instance (array of strings or ["ANY"]). Default is ["ANY"] (all backends available on the plan). Use [] for no backends.

Instance extensions

When you retrieve instance details via the IBM Cloud Resource Controller API, the response includes an extensions property with additional instance information:

  • instance_limit_seconds: The time limit set on the instance (integer or null, ≥ 0)
  • usage_allocation_seconds: Allotted time for the instance (integer or null, ≥ 0)
  • backends: The allow-list of backend names available to this instance (required array)

For complete details on parameters and extensions, including examples and API endpoints, see Use IBM Cloud Platform APIs to access instances.

Use the Qiskit Runtime REST API

The following sections describe how to use the Qiskit Runtime REST API to submit jobs and manage sessions. These operations require authentication and an existing instance.

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, CRN, and IBM-API-Version on every request within an Authorization and Service-CRN header with this format:

Authorization: Bearer <YOUR_BEARER_TOKEN>
Service-CRN: <YOUR_INSTANCE_CRN>
IBM-API-Version: <YYYY-MM-DD>

Example request:

eu-de region

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/backends

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>' \
    -H 'IBM-API-Version: 2026-03-15'

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 your IBM Cloud instance CRN.
  • 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:

eu-de region

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

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 'IBM-API-Version: 2026-03-15' \
  -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):

eu-de region

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions

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 'IBM-API-Version: 2026-03-15' \
  -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:

eu-de region

If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/jobs

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 'IBM-API-Version: 2026-03-15' \
  -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, typo, or request content on GitHub.