--- title: Execution modes using REST API description: How to run a quantum computing job in an IBM Quantum Compute Service session. source: https://eu-de.quantum.cloud.ibm.com/docs/en/guides/execution-modes-rest-api --- # Execution modes using REST API ### Package versions The code on this page was developed using the following requirements. We recommend using these versions or newer. ``` qiskit[all]~=2.3.0 ``` You can run your IBM Quantum 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 IBM Quantum Compute Service 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](/docs/api/qiskit-runtime-rest) for details. ## Job mode with REST API In job mode, a single primitive request of Estimator or Sampler is made without a context manager. See how to run a quantum circuit using [Estimator](/docs/guides/estimator-rest-api) and [Sampler](/docs/guides/sampler-rest-api) for some examples. ## Session mode with REST API A session is a 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](/docs/guides/execution-modes). > **Note** > > Open Plan users cannot submit session jobs. ### Start a session Begin by creating a session and obtaining a session ID. ```python import json import requests sessionsUrl = "https://quantum.cloud.ibm.com/api/v1/sessions" auth_id = "Bearer " backend = "" crn = "" headersList = { "Accept": "application/json", "Content-Type": "application/json", "Authorization": auth_id, "Service-CRN": crn } payload = json.dumps({ "backend": backend, "mode": 'dedicated', }) response = requests.request("POST", sessionsUrl, data=payload, headers=headersList) sessionId = response.json()['id'] print(response.json()) ``` Output ```text {'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. ```python closureURL="https://quantum.cloud.ibm.com/api/v1/sessions/"+sessionId+"/close" headersList = { "Accept": "application/json", "Authorization": auth_id, "Service-CRN": crn } closure_response = requests.request( "DELETE", closureURL, headers=headersList ) print("Session closure response ok?:",closure_response.ok,closure_response.text) ``` Output ```text 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. Learn about batch mode in the [introduction to execution modes](/docs/guides/execution-modes#batch-mode) guide. ```python import json import requests sessionsUrl = "https://quantum.cloud.ibm.com/api/v1/sessions" headersList = { "Accept": "application/json", "Authorization": auth_id, "Service-CRN": crn, '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 `` in a `PUB` can either be a single parameter or a list of parameters. It also supports `numpy` broadcasting. ### Estimator jobs in session mode ### 1 circuit, 4 observables ```python job_input = { 'program_id': 'estimator', "backend": backend, "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. "options":{ "transpilation":{"optimization_level": 1}, "twirling": {"enable_gates": True,"enable_measure": True}, # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"}, #(optional) }, } } ``` ### 1 circuit, 4 observables, 2 parameter sets ```python job_input = { 'program_id': 'estimator', "backend": backend, "session_id": sessionId, # This specifies the previously created Session "params": { "pubs": [[resulting_qasm, [[obs1], [obs2], [obs3], [obs4]], [[vals1], [vals2]]]], #primitive unified blocs (PUBs) containing one circuit each "options":{ "transpilation":{"optimization_level": 1}, "twirling": {"enable_gates": True,"enable_measure": True}, # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"}, #(optional) }, } } ``` ### 2 circuits, 2 observables ```python job_input = { 'program_id': 'estimator', "backend": backend, "session_id": sessionId, # This specifies the previously created Session "params": { "pubs": [[resulting_qasm, obs1],[resulting_qasm, obs2]], #primitive unified blocs (PUBs) containing one circuit each "options":{ "transpilation":{"optimization_level": 1}, "twirling": {"enable_gates": True,"enable_measure": True}, # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"}, #(optional) }, } } ``` ### Sampler jobs in session mode ### 1 circuit, no parameters ```python job_input = { 'program_id': 'sampler', "backend": backend, "session_id": sessionId, # This specifies the previously created Session "params": { "pubs": [[resulting_qasm]], #primitive unified blocs (PUBs) containing one circuit each "options":{ "transpilation":{"optimization_level": 1}, "twirling": {"enable_gates": True,"enable_measure": True}, # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"}, #(optional) }, } } ``` ### 1 circuit, 3 parameter sets ```python job_input = { 'program_id': 'sampler', "backend": backend, "session_id": sessionId, # This specifies the previously created Session "params": { "pubs": [[resulting_qasm, [vals1, vals2, vals3]]], #primitive unified blocs (PUBs) containing one circuit each "options":{ "transpilation":{"optimization_level": 1}, "twirling": {"enable_gates": True,"enable_measure": True}, # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"}, #(optional) }, } } ``` ### 2 circuits, 1 parameter set ```python job_input = { 'program_id': 'sampler', "backend": backend, "session_id": sessionId, # This specifies the previously created Session "params": { "pubs": [[resulting_qasm, [val1]],[resulting_qasm,None,100]], #primitive unified blocs (PUBs) containing one circuit each "options":{ "transpilation":{"optimization_level": 1}, "twirling": {"enable_gates": True,"enable_measure": True}, # "dynamical_decoupling": {"enable": True, "sequence_type": "XpXm"}, #(optional) }, } } ``` ## Next steps > **Recommendations** > > - Review detailed [Sampler](/docs/guides/sampler-rest-api) primitives examples using REST API. > - Review detailed [Estimator](/docs/guides/estimator-rest-api) primitives examples using REST API. > - Practice with primitives by working through the [Cost function lesson](/learning/courses/variational-algorithm-design/cost-functions) in IBM Quantum® Learning. > - Learn how to transpile locally in the [Transpile](/docs/guides/transpile) section.