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.

Note

This documentation applies to the IBM Quantum™ channel. If you are accessing Qiskit Runtime through IBM Cloud®, you can find the API documentation here.

Authentication

You must provide an API token with every call as an http header. You can copy your API token from your Dashboard, near the top for easy access.

Then, submit your API token on every request within an Authorization header with this format:

Authorization: Bearer YOUR_API_TOKEN_HERE

Example request:

curl -X 'GET' \
  'https://api.quantum-computing.ibm.com/runtime/jobs?limit=10&offset=0&exclude_params=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN_HERE'

import requests
 
reqUrl = "https://api.quantum-computing.ibm.com/runtime/jobs?limit=10&offset=0&exclude_params=true"
 
headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN_HERE"
}
 
payload = ""
 
response = requests.request("GET", reqUrl, data=payload,  headers=headersList)
 
print(response.json())

Submit a job

Note the following when submitting a job:

Use the create job operation to submit primitives 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://api.quantum-computing.ibm.com/runtime/jobs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOU_API_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "estimator",
  "backend": "ibm_brisbane",
  "hub": "ibm-q",
  "group": "open",
  "project": "main",
  "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
  }
}'

import requests
import json
 
reqUrl = "https://api.quantum-computing.ibm.com/runtime/jobs"
 
headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN_HERE",
  "Content-Type": "application/json"
}
 
payload = json.dumps({
  "program_id": "estimator",
  "backend": "ibm_brisbane",
  "hub": "ibm-q",
  "group": "open",
  "project": "main",
  "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
  }
})
 
response = requests.request("POST", reqUrl, data=payload,  headers=headersList)
 
print(response.json())

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://api.quantum-computing.ibm.com/runtime/sessions' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "backend": "ibm_brisbane",
  "instance": "ibm-q/open/main"
}'

import requests
import json
 
reqUrl = "https://api.quantum-computing.ibm.com/runtime/sessions"
 
headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN_HERE",
  "Content-Type": "application/json"
}
 
payload = json.dumps({
  "backend": "ibm_brisbane",
  "instance": "ibm-q/open/main"
})
 
response = requests.request("POST", reqUrl, data=payload,  headers=headersList)
 
sessionId = response.json()['id']
 
print(response.json())
print(sessionId)

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://api.quantum-computing.ibm.com/runtime/jobs' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "program_id": "sampler",
  "backend": "ibm_brisbane",
  "hub": "ibm-q",
  "group": "open",
  "project": "main",
  "session_id": "session_id1",
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;"
    ]],
    "options": {},
    "version": 2
  }
}'

import requests
import json
 
reqUrl = "https://api.quantum-computing.ibm.com/runtime/jobs"
 
headersList = {
  "Accept": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN_HERE",
  "Content-Type": "application/json"
}
 
## Session ID
sessionId = "session_id1"
 
payload = json.dumps({
  "program_id": "sampler",
  "backend": "ibm_brisbane",
  "hub": "ibm-q",
  "group": "open",
  "project": "main",
  "session_id": sessionId,
  "params": {
    "pubs": [[
      "OPENQASM 3.0; include \"stdgates.inc\"; bit[1] c; x $0; c[0] = measure $0;"
    ]],
    "options": {},
    "version": 2
  }
})
 
response = requests.request("POST", reqUrl, data=payload,  headers=headersList)
 
print(response.json())

Was this page helpful?

Report a bug or request content on GitHub.