---
title: Sampler (latest version)
description: API reference for qiskit_ibm_runtime.executor_sampler.Sampler in the latest version of qiskit-ibm-runtime
source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-ibm-runtime/executor-sampler-sampler
---

# Sampler

*class* `Sampler(mode=None, options=None)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.50/qiskit_ibm_runtime/executor_sampler/sampler.py#L47-L235)

Bases: [`BaseSamplerV2`](/docs/api/qiskit/qiskit.primitives.BaseSamplerV2)

Client-side Sampler primitive for IBM Quantum Compute (formerly Qiskit Runtime).

This is an implementation of Sampler built on top of the Executor primitive, enabling transparent client-side processing with faster feedback loops and greater user control.

**Limitations:**

- When twirling is disabled, circuits must not contain [`BoxOp`](/docs/api/qiskit/qiskit.circuit.BoxOp) instructions.
- Dynamical decoupling is incompatible with dynamic circuits.

**Example**

```python
from qiskit import QuantumCircuit
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime.executor_sampler import Sampler

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

# Create a simple circuit
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

# Run the sampler with options
sampler = Sampler(mode=backend)
sampler.options.default_shots = 2048
sampler.options.execution.init_qubits = True
job = sampler.run([circuit])
result = job.result()
```

**Parameters**

- **mode** (*BackendV2 |* [*Session*](/docs/api/qiskit-ibm-runtime/session "qiskit_ibm_runtime.Session")  *|*[*Batch*](/docs/api/qiskit-ibm-runtime/batch "qiskit_ibm_runtime.Batch") *| None*) –

  The execution mode used to make the primitive query. It can be:

  - A [`BackendV2`](/docs/api/qiskit/qiskit.providers.BackendV2) if you are using job mode.
  - A [`Session`](/docs/api/qiskit-ibm-runtime/session "qiskit_ibm_runtime.Session") if you are using session execution mode.
  - A [`Batch`](/docs/api/qiskit-ibm-runtime/batch "qiskit_ibm_runtime.Batch") if you are using batch execution mode.

  Refer to the [IBM Quantum Compute documentation](/docs/guides/execution-modes) for more information about execution modes.

- **options** ([*SamplerOptions*](/docs/api/qiskit-ibm-runtime/options-models-sampler-options "qiskit_ibm_runtime.options_models.sampler.SamplerOptions")) – Sampler options. See [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-models-sampler-options "qiskit_ibm_runtime.options_models.SamplerOptions") for all available options.

## Attributes

### mode

Return the execution mode used by this primitive.

**Returns**

Mode used by this primitive, or `None` if an execution mode is not used.

### options

Type: [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-models-sampler-options "qiskit_ibm_runtime.options_models.sampler.SamplerOptions")

The options of this Sampler.

## Methods

### backend

`backend()`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.50/qiskit_ibm_runtime/executor_sampler/sampler.py#L129-L131)

Return the backend the primitive query will be run on.

**Return type**

BackendV2

### finalize\_options

`finalize_options()`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.50/qiskit_ibm_runtime/executor_sampler/sampler.py#L171-L182)

Construct and finalize the Sampler options.

This method produces the final [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-models-sampler-options "qiskit_ibm_runtime.options_models.SamplerOptions") instance used inside a call to [`run()`](#qiskit_ibm_runtime.executor_sampler.Sampler.run "qiskit_ibm_runtime.executor_sampler.Sampler.run") by resolving the `None` in the twirling options as documented in [`TwirlingOptions`](/docs/api/qiskit-ibm-runtime/options-models-twirling-options "qiskit_ibm_runtime.options_models.TwirlingOptions").

**Returns**

The finalized [`SamplerOptions`](/docs/api/qiskit-ibm-runtime/options-models-sampler-options "qiskit_ibm_runtime.options_models.SamplerOptions") object.

**Return type**

[*SamplerOptions*](/docs/api/qiskit-ibm-runtime/options-models-sampler-options "qiskit_ibm_runtime.options_models.sampler.SamplerOptions")

### find\_unique\_layers

`find_unique_layers(pubs, types='gates')`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.50/qiskit_ibm_runtime/executor_sampler/sampler.py#L142-L169)

Return the unique boxed layers found across the given PUBs of a given type.

The `types` of layers can be either `"gates"` or `"all"`, corresponding to only gate layers or all layers, respectively. The returned list then contains one instance of each distinct boxed layer (represented as a `CircuitInstruction`) appearing in the input PUBs.

**Parameters**

- **pubs** (*Iterable\[SamplerPubLike]*) – The list of PUBs to return a list of unique boxes for.
- **types** (*Literal\['gates', 'all']*) – The types of layers to return. Can be either `"gates"` or `"all"`.

**Returns**

The unique boxed layers of a certain type found across the given PUBs.

**Return type**

list\[CircuitInstruction]

### run

`run(pubs, *, shots=None, dry_run=False)`

[GitHub](https://github.com/Qiskit/qiskit-ibm-runtime/tree/stable/0.50/qiskit_ibm_runtime/executor_sampler/sampler.py#L184-L235)

Submit a request to the sampler primitive.

For moderate and complex workloads, the client-side processing done to map sampler inputs to executor inputs can be resource intensive and cause a delay between invoking the function and the `job` being submitted. In order to check the progress of the call, it is recommended to setup logging (with an `INFO` level) - see [IBM Quantum Compute documentation](/docs/api/qiskit-ibm-runtime/runtime-service#logging) for more information.

**Parameters**

- **pubs** (*Iterable\[SamplerPubLike]*) – An iterable of pub-like objects. For example, a list of circuits or tuples `(circuit, parameter_values)`.
- **shots** (*int | None*) – The total number of shots to sample for each sampler pub that does not specify its own shots. If `None`, the value from `options.default_shots` will be used.
- **dry\_run** (*bool*) – If `True`, performs a dry run without executing the job on a QPU. This mode can be used to validate the job, estimate usage consumption, and retrieve circuit timing metadata. Returned results preserve the expected schema but contain **randomized mock data** rather than actual or simulated measurement results. Unlike the fake backends, the processing of this dry run happens on the server-side, so the job may not finish immediately and access to this feature may be restricted.

**Returns**

The submitted job.

**Return type**

[RuntimeJobV2](/docs/api/qiskit-ibm-runtime/runtime-job-v2 "qiskit_ibm_runtime.RuntimeJobV2") | LocalRuntimeJob