Skip to main contentIBM Quantum Documentation

Introduction to Qiskit Runtime


This documentation is based on Qiskit Runtime version 0.12.1.

Qiskit Runtime is a cloud-based quantum computing service developed by IBM. It offers computational primitives to perform foundational quantum computing tasks that use built-in error suppression and mitigation techniques. Primitives can be executed inside of sessions, so that collections of circuits can jointly run on a quantum computer without being interrupted by other users’ jobs. The combination of primitives, error suppression / mitigation, and sessions paves the way to efficiently build and execute scalable quantum applications, as shown in the code examples.

The following figure illustrates how one can use Qiskit Runtime sessions and primitives. The first session request (job) waits through the regular fair-share queue. When it starts to run, the session is started. After the first session job is finished processing, the next job in the session is run. This process continues until the session is paused (due to a lack of queued session jobs) or closed.

Qiskit Runtime architecture diagram.
Figure 1: Qiskit Runtime architecture

Benefits of using Qiskit Runtime:

  • Simplify algorithm design and optimization.
  • Run circuits faster by using sessions - a context manager designed to efficiently manage iterative workloads and minimize artificial latency between quantum and classical sub-components.
  • Access our most powerful quantum systems with our latest performance and hardware optimization, including capabilities like error suppression and mitigation.
  • Easily integrate Qiskit Runtime with your cloud or on-premise classical compute resources by using the Quantum serverless (opens in a new tab) toolkit.

Simplified interface:

Use primitive programs to write code more efficiently. For details, see the Migration examples topic.

Without using primitives
def get_evaluate_energy_vqe(
    ansatz: QuantumCircuit,
    operator: OperatorBase,
    return_expectation: bool = False,
) -> Callable[[np.ndarray], np.ndarray | float]:
    num_parameters = ansatz.num_parameters
    ansatz_params = ansatz.parameters
    expect_op, expectation = self.construct_expectation(
        ansatz_params, operator, return_expectation=True
    def evaluate_energy(parameters: np.ndarray):
        parameter_sets = np.reshape(parameters, (-1, num_parameters))
        # Create dict associating each parameter with the lists of parameterization values for it
        param_bindings = dict(zip(ansatz_params, parameter_sets.transpose().tolist()))
        sampled_expect_op = self._circuit_sampler.convert(expect_op, params=param_bindings)
        means = np.real(sampled_expect_op.eval())
        return means if len(means) > 1 else means[0]
    if return_expectation:
        return evaluate_energy, expectation
    return evaluate_energy
Using primitives
def _get_evaluate_energy_vqe_primitives(
    ansatz: QuantumCircuit,
    operator: BaseOperator | PauliSumOp,
) -> Callable[[np.ndarray], np.ndarray | float]:
    num_parameters = ansatz.num_parameters
    def evaluate_energy(parameters: np.ndarray):
        parameters = np.reshape(parameters, (-1, num_parameters)).tolist()
        batch_size = len(parameters)
        job = * [ansatz], batch_size * [operator], parameters)
        estimator_result = job.result()
        values = estimator_result.values
        return values[0] if len(values) == 1 else values
    return evaluate_energy


Primitives are base level operations that serve as building blocks for many quantum algorithms and applications. Through these primitives, users can obtain high-fidelity results without needing detailed hardware knowledge. This abstraction allows you to write code, using Qiskit algorithms or otherwise, that can run on various quantum hardware or simulators without having to explicitly manage aspects such as compilation, optimization, and error suppression / mitigation. The primitives offered by qiskit_ibm_runtime add additional options specific to IBM services. See Introduction to primitives for further details. There are currently two primitives defined in Qiskit: Estimator and Sampler.


The Estimator primitive allows you to efficiently calculate and interpret expectation values of quantum operators, which are the values of interest for many near-term quantum algorithms. You specify circuits that prepare quantum states and then Pauli-basis observables to measure on those states. Estimator can use advanced error suppression and mitigation capabilities to improve the accuracy of the returned expectation values. Get started with the Estimator primitive here.


This primitive takes circuits as input and returns a quasi-probability distribution over the measurement outcomes. This generalizes histograms from quantum circuits, allowing for mitigation of readout errors. Get started with the Sampler primitive tutorial here.


Runtime sessions can be used in conjunction with Qiskit Runtime primitives. A session allows a collection of jobs to be grouped and jointly scheduled by the Qiskit Runtime service, facilitating iterative use of quantum computers without incurring queuing delays on each iteration. This eliminates artificial delays caused by other users’ jobs running on the same quantum device during the session. See the sessions topic for more information.

Error suppression / mitigation

While building a fault-tolerant quantum computation is the ultimate goal, at present, calculations performed on near-term quantum computers are susceptible to noise. Qiskit Runtime offers a number of methods for preventing errors before they occur (error suppression techniques) and dealing with those that do occur (error mitigation techniques). See Configure error suppression and Configure error mitigation for details.

Runtime FAQs

What is the difference between the open source primitives and primitives available through Qiskit Runtime?

The open-source primitive contains the base classes (to define interfaces) and a reference implementation. The Qiskit Runtime primitives provide more sophisticated implementation (such as with error mitigation) as a cloud-based service.

What is the maximum execution time for a Qiskit Runtime job or session?

To ensure fairness and to help control cost, there is a maximum amount of time each Qiskit Runtime job can run. If a job exceeds this time limit, it is forcibly canceled and a RuntimeJobMaxTimeoutError exception is raised. This maximum time is the smallest of these values:

  • The max_execution_time defined by the job
  • The max_time defined by the session (does not apply to simulator jobs)
  • The system-calculated timeout

See Maximum execution time for full details.

Next steps

Was this page helpful?