Experiment with Qiskit Runtime

Qiskit Runtime is used to run IBM Quantum programs. Learn how these runtime programs work by trying out a prebuilt program.


Qiskit Runtime speeds up processing time by combining classical and quantum computing in a streamlined architecture.

In this first version you can explore running simple circuits or more complex variational algorithms (based on VQE). Additionally, you can test it using our quantum simulators on the cloud, so that you can quickly get up to speed with this new way to run Qiskit programs. With Qiskit Runtime, you can keep your quantum program on the cloud and run it any time.

Diagram of Qiskit Runtime's architecture.

Diagram of Qiskit Runtime’s architecture.

Many of the following tasks can be carried out by using the Qiskit Runtime REST API , if that is your preferred method.

View available Qiskit Runtime programs

The Programs page displays all available programs. Click any program to learn more about it, and optionally choose a backend and provider to generate a custom program template and open it directly in Quantum Lab. You can then modify it as necessary and use it to execute circuits.

Run a Qiskit Runtime program

In this example we will use a preloaded Qiskit Runtime program called sampler. We will first build a circuit using Qiskit, then execute it with Qiskit Runtime, taking advantage of its low-latency architecture.


  • You will need the latest qiskit and qiskit-ibm-runtime packages to use Qiskit Runtime.

  • Read about the maximum execution time for a Qiskit Runtime job here.

The sampler program is one of the primitive programs (another is the estimator). These primitives provide methods that make it easier to build modular algorithms and other higher-order programs. They provide a seamless way to leverage the latest optimizations in IBM Quantum hardware and software.

The Sampler primitive lets you more accurately contextualize counts. It takes a user circuit as an input and generates a readout of quasi-probabilities. This enables you to more efficiently evaluate the possibility of multiple relevant data points in the context of destructive interference.

qiskit-ibm-runtime now provides a simple Sampler class which allows access to the Sampler primitive service.

Instantiate the QiskitRuntimeService from one of the saved accounts like below.

from qiskit_ibm_runtime import QiskitRuntimeService, Sampler

# Save your credentials on disk.
# QiskitRuntimeService.save_account(channel='ibm_quantum', token=<IBM Quantum API key>)

service = QiskitRuntimeService()

A Qiskit Runtime session allows you to cache data, such as parameterized circuits, on the server side for the duration of a session. You can then pass in only parameters during subsequent calls.

Let’s prepare the quantum circuits as shown below.

from qiskit import QuantumCircuit

bell = QuantumCircuit(2)
bell.cx(0, 1)

        ┌───┐      ░ ┌─┐
   q_0: ┤ H ├──■───░─┤M├───
        └───┘┌─┴─┐ ░ └╥┘┌─┐
   q_1: ─────┤ X ├─░──╫─┤M├
             └───┘ ░  ║ └╥┘
meas: 2/══════════════╩══╩═
                      0  1

The quantum circuits can then be passed as lists to the Sampler class, which instantiates and opens a session with the Sampler primitive service.

sampler can then be called multiple times to write different circuit_indices (a list of circuit indices) and parameter_values (an optional list of concrete parameters to be bound) to the session and read the calculated quasi-probabilities. The result is an instance of SamplerResult class in qiskit-terra and it contains quasi-probabilities and metadata.

with Sampler(circuits=[bell]*3, service=service, options={ "backend": "ibmq_qasm_simulator" }) as sampler:
    result1 = sampler(circuit_indices=[0, 1, 2], shots=2000)

    result2 = sampler(circuit_indices=[0, 1, 2], shots=3000)

    result3 = sampler(circuit_indices=[0, 1, 2], shots=4000)
SamplerResult(quasi_dists=[{'00': 0.5155, '11': 0.4845}, {'11': 0.5175, '00': 0.4825}, {'00': 0.4915, '11': 0.5085}], metadata=[{'header_metadata': None, 'shots': 2000}, {'header_metadata': None, 'shots': 2000}, {'header_metadata': None, 'shots': 2000}])
SamplerResult(quasi_dists=[{'11': 0.5043333333333333, '00': 0.49566666666666664}, {'00': 0.501, '11': 0.499}, {'00': 0.493, '11': 0.507}], metadata=[{'header_metadata': None, 'shots': 3000}, {'header_metadata': None, 'shots': 3000}, {'header_metadata': None, 'shots': 3000}])
SamplerResult(quasi_dists=[{'00': 0.495, '11': 0.505}, {'11': 0.50075, '00': 0.49925}, {'11': 0.49825, '00': 0.50175}], metadata=[{'header_metadata': None, 'shots': 4000}, {'header_metadata': None, 'shots': 4000}, {'header_metadata': None, 'shots': 4000}])

View your Qiskit program jobs

You can view details about running and completed jobs by opening the Jobs page from the application switcher ( switcher ), then clicking the Program jobs tab.

Qiskit Runtime tutorials and other resources

To learn more, visit the Qiskit Runtime Github repository. You can also implement Qiskit Runtime by using the public REST API.

Explore these Qiskit Runtime tutorials:



Qiskit Runtime is still in beta mode, and heavy modifications to both functionality and API are likely to occur. Some of the changes might not be backward-compatible and would require updating your Qiskit version.

Qiskit Runtime glossary

Qiskit program

Qiskit Python source code that describes the problem to solve, combining classical and quantum computation. It takes inputs from the users, makes the calculation, and returns the results. Each instance of a Qiskit program execution is similar to a computer process and is represented as a runtime job.

Qiskit program metadata

The data that defines your program. Critical components are name, maximum execution time, version, backend requirements, and input/output parameters.

Qiskit Runtime

Qiskit Runtime is a cloud service that runs the Qiskit program remotely as a process, passing the input from the user, and handling the connectivity between the Qiskit program, the user, and the quantum processing unit. You can repeat this multiple times with the same or different Qiskit programs.

Qiskit Runtime manager

The main task of this component of the architecture is to prepare Qiskit Runtime, load the Qiskit programs, and supervise the correct execution.

OpenQASM circuit

Quantum circuit format generated by the Qiskit program. OpenQASM is the low-level language consumed by the Quantum Processing Unit (QPU).

Quantum processing unit (QPU)

Part of the computational unit that performs the quantum computation.