Qiskit IBM Runtime REST API

The Qiskit IBM Runtime REST API allows you to run on quantum systems 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 systems 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(opens in a new tab).

Authentication

You must provide an API token with every call as an http header. You can copy your API token from your Dashboard(opens in a new tab), 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 system, 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(opens in a new tab) section of IBM Quantum Platform.

Example request creating a sampler job with one circuit:

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": "sampler",
  "backend": "ibm_brisbane",
  "hub": "ibm-q",
  "group": "open",
  "project": "main",
  "params": {
    "circuits": [
      "OPENQASM 3; include \"stdgates.inc\"; qreg q[1]; creg c[1]; x q[0]; c[0] = measure q[0];"
    ]
  }
}'

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": "sampler",
  "backend": "ibm_brisbane",
  "hub": "ibm-q",
  "group": "open",
  "project": "main",
  "params": {
    "circuits": [
      "OPENQASM 3; include \"stdgates.inc\"; qreg q[1]; creg c[1]; x q[0]; c[0] = measure q[0];"
    ]
  }
})
 
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": {
    "circuits": [
      "OPENQASM 3; include \"stdgates.inc\"; qreg q[1]; creg c[1]; x q[0]; c[0] = measure q[0];"
    ]
  }
}'

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": {
    "circuits": [
      "OPENQASM 3; include \"stdgates.inc\"; qreg q[1]; creg c[1]; x q[0]; c[0] = measure q[0];"
    ]
  }
})
 
response = requests.request("POST", reqUrl, data=payload,  headers=headersList)
 
print(response.json())

Was this page helpful?

Report a bug or request content on GitHub.