Skip to main contentIBM Quantum Documentation

Execution modes using REST API

You can run your Qiskit primitive workloads using REST APIs in one of three execution modes, depending on your needs: job, session, and batch. This topic explains these modes.

Note

This documentation utilizes the Python requests module to demonstrate the Qiskit Runtime REST API. However, this workflow can be executed using any language or framework that supports working with REST APIs. Refer to the API reference documentation for details.

Job mode with REST API

In job mode, a single primitive request of the Estimator or the Sampler is made without a context manager. See how to run a quantum circuit using Estimator and Sampler for some examples.

Session mode with REST API

A session is a Qiskit Runtime feature that lets you efficiently run multi-job iterative workloads on quantum computers. Using sessions helps avoid delays caused by queuing each job separately, which can be particularly useful for iterative tasks that require frequent communication between classical and quantum resources. More details about Sessions can be found in the documentation.

Start a session

Begin with creating a session and obtaining a session ID.

import json
 
sessionsUrl = "https://api.quantum-computing.ibm.com/runtime/sessions"
 
headersList = {
  "Accept": "application/json",
  'x-access-token':auth_id,
  "Content-Type": "application/json"
}
 
payload = json.dumps({
  "backend": backend,
  "instance": "hub1/group1/project1",
})
 
response = requests.request("POST", sessionsUrl, data=payload,  headers=headersList)
 
sessionId = response.json()['id']
 
print(response.json())

Output

{'id': 'crw9s7cdbt40008jxesg'}

Close a session

It is good practice to close a Session when all jobs are done. This will reduce wait time for subsequent users.

closureURL="https://api.quantum-computing.ibm.com/runtime/sessions/"+sessionId+"/close"
 
headersList = {
  "Accept": "application/json",
  'x-access-token':auth_id,
}
 
closure_response = requests.request(
    "DELETE",
    closureURL,
    headers=headersList)
 
print("Session closure response ok?:",closure_response.ok,closure_response.text)

Output

Session closure response ok?: True

Batch mode with REST API

Alternatively, you can submit a batch job by specifying the mode in the request payload. Batch mode can help shorten processing time if all jobs can be provided at the outset. More details about batch mode can be found in the documentation.

import json
 
sessionsUrl = "https://api.quantum-computing.ibm.com/runtime/sessions"
 
headersList = {
  "Accept": "application/json",
  'x-access-token':auth_id,
  "Content-Type": "application/json"
}
 
payload = json.dumps({
  "backend": backend,
  "instance": "hub1/group1/project1",
  "mode": "batch"
})
 
response = requests.request("POST", sessionsUrl, data=payload,  headers=headersList)
 
sessionId = response.json()['id']

Examples of jobs submitted in a session

Once a session is set up, one or more Sampler or Estimator jobs can be submitted to the same session by specifying the session ID.

Note

The <parameter values> in a PUB can either be a single parameter or a list of parameters. It also supports numpy broadcasting.

Estimator jobs in session mode

job_input = {
'program_id': 'estimator',
"backend": backend,
"hub": "hub1",
"group": "group1",
"project": "project1",
"session_id": sessionId, # This specifies the previously created Session
"params": {
    "pubs": [[resulting_qasm, [obs1, obs2, obs3, obs4]]], #primitive unified blocs (PUBs) containing one circuit each. c.f. https://docs.quantum.ibm.com/migration-guides/v2-primitives
    "version": 2, #this defines the version of the Qiskit Runtime Primitive to use, c.f. https://docs.quantum.ibm.com/migration-guides/v2-primitives
    "options":{
            "transpilation":{"optimization_level": 1},
            "twirling": {"enable_gates": True,"enable_measure": True}, #c.f. documentation at https://docs.quantum.ibm.com/run/configure-error-mitigation#custom-error-settings-v2-primitives
            # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"},   #(optional)
                },
}
 
}

Sampler jobs in session mode

job_input = {
'program_id': 'sampler',
"backend": backend,
"hub": "hub1",
"group": "group1",
"project": "project1",
"session_id": sessionId, # This specifies the previously created Session
"params": {
    "pubs": [[resulting_qasm]], #primitive unified blocs (PUBs) containing one circuit each. c.f. https://docs.quantum.ibm.com/migration-guides/v2-primitives
    "version": 2, #this defines the version of the Qiskit Runtime Primitive to use, c.f. https://docs.quantum.ibm.com/migration-guides/v2-primitives
    "options":{
            "transpilation":{"optimization_level": 1},
            "twirling": {"enable_gates": True,"enable_measure": True}, #c.f. documentation at https://docs.quantum.ibm.com/run/configure-error-mitigation#custom-error-settings-v2-primitives
            # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"},   #(optional)
                },
}
 
}

Next steps

Recommendations
Was this page helpful?
Report a bug or request content on GitHub.