Run on qBraid

QbraidProvider runs your circuits on any device in the qBraid device catalog with one qBraid API key. You need no account with the hardware vendor. Jobs are billed in qBraid credits and show up in your qBraid Quantum Jobs. The one exception is devices with openquantum: IDs, which need a linked Open Quantum account and spend its credits. This is how most people use the qBraid SDK.

Devices on qBraid

Each vendor page lists that vendor’s device IDs and how to get the most out of them through qBraid:

The device catalog is the live list, with each device’s status and price. provider.get_devices() returns the same list from Python.

Submission paths

The first part of a device ID says how qBraid reaches the device. Some vendors are reachable more than one way, and each vendor page has a section per path.

Installation & Setup

Install the qBraid SDK:

pip install qbraid

Next, obtain your qBraid API key:

1. Login or create an account at account.qbraid.com.
2. Navigate to Account > API Keys in the left-sidebar, and then click “Create API Key”.

Save account to disk

Once you have your API key, you can save it locally in a configuration file ~/.qbraid/qbraidrc, where ~ corresponds to your home ($HOME) directory:

from qbraid.runtime import QbraidProvider

provider = QbraidProvider(api_key='API_KEY')
provider.save_config()

Once the account is saved on disk, you can instantiate the provider without any arguments:

provider = QbraidProvider()

Load account from environment variables

Alternatively, the qBraid-SDK can discover credentials from environment variables:

export QBRAID_API_KEY='QBRAID_API_KEY'

Basic Usage

Given a device “QRN” (qBraid Resource Name), a QbraidDevice object can be created as follows:

from qbraid import QbraidProvider

provider = QbraidProvider()
provider.get_devices()
# [<qbraid.runtime.native.device.QbraidDevice('qbraid:qbraid:sim:qir-sv')>]

device = provider.get_device('qbraid:qbraid:sim:qir-sv')

type(device)
# <class 'qbraid.runtime.native.device.QbraidDevice'>

From here, class methods are available to get information about the device, execute quantum programs, access the wrapped device object directly, and more.

device.metadata()
# {'device_id': 'qbraid:qbraid:sim:qir-sv',
#  'device_type': 'SIMULATOR',
#  'num_qubits': 30,
#  'status': 'ONLINE',
#  'queue_depth': 0}

Then you can submit quantum jobs to the device.

run_input = [qiskit_circuit, braket_circuit, cirq_circuit, qasm3_str]

jobs = device.run(run_input, shots=100)

results = [job.result() for job in jobs]

print(results[0].data.get_counts())
# {'00': 50, '01': 2, '10': 47, '11': 1}

See how to visualize these results in the Visualization section.

Runtime Options

When submitting jobs through the QbraidProvider, you can pass provider-specific options using the runtime_options keyword argument. These options are forwarded directly to the underlying cloud provider’s submission API, giving you access to device-specific features without needing to configure provider credentials yourself.

job = device.run(circuit, shots=100, runtime_options={"key": "value"})

The runtime_options dictionary is passed through as-is to the provider backend:

• Amazon Braket (aws:*) devices: options are unpacked as keyword arguments to the Braket device.run() call
• Azure Quantum (azure:*) devices: options are passed as input_params to the Azure device.run() or device.submit() call
• Other devices: options are merged into the job submission payload

qBraid Simulator Examples

Pass a seed to make a simulation reproducible. Two runs of the same circuit with the same seed return identical measurement counts:

device = provider.get_device("qbraid:qbraid:sim:qir-sv")

job = device.run(circuit, shots=100, runtime_options={"seed": 42})

print(job.result().data.get_counts())
# {'00': 48, '11': 52}

Submitting the same circuit again with "seed": 42 returns those same counts. Change the seed, or leave it out, and the simulator draws a fresh sample on every run.

This is useful for tutorials and course material where the output in the text should match what the reader sees, for regression tests that assert on exact counts, and for sharing a result someone else can reproduce.

The GPU simulators, qbraid:qbraid:sim:gpu-sv (state vector, up to 35 qubits) and qbraid:qbraid:sim:gpu-tn (tensor network, up to 500 qubits), take seed the same way, alongside their own options, such as precision, method, and maxBondDim:

device = provider.get_device("qbraid:qbraid:sim:gpu-tn")

job = device.run(
    qasm3_str, shots=1000, runtime_options={"method": "mps", "maxBondDim": 256, "seed": 42}
)

See GPU simulators for every option, their limits, and their daily allowance.

Vendor-specific options

Every aws: device takes the Braket runtime options. Options specific to a vendor’s direct path are on its page: IonQ, Quobly and Rigetti.

Next Steps

• Managing jobs: estimating cost, tracking a job, reading its cost and timing, and getting it back later
• Batch & group jobs: running several circuits as separate, batch, or group jobs
• Calibrations: live calibration data for choosing qubits
• Devices on qBraid: the page for the vendor you want to run on