Job Execution - qBraid

API Reference: qbraid.runtime.native

This page covers how to submit quantum jobs through the QbraidProvider — from single one-off submissions, to batching multiple circuits in a single job, to grouped workflows that span multiple devices and providers. For provider setup and authentication, see QbraidProvider - Usage.

Single Job Submission

Submit a quantum program to any qBraid-supported device and retrieve results:

from qbraid.runtime import QbraidProvider

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

# Define a quantum program (QASM, Qiskit, Cirq, Braket, etc.)
bell = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;
"""

# Submit and wait for results
job = device.run(bell, shots=100)
result = job.result()
print(result.data.get_counts())
# {'00': 52, '11': 48}

For async applications, you can use async_result() to await job completion without blocking the event loop:

result = await job.async_result(timeout=120, poll_interval=5)
print(result.data.get_counts())

You can also submit multiple programs at once — each is executed as a separate job:

programs = [bell_circuit, ghz_circuit, qft_circuit]
jobs = device.run(programs, shots=100)
results = [job.result() for job in jobs]

Group Jobs

Why Group?

When running related quantum experiments — parameter sweeps, algorithm comparisons, cross-device benchmarks — you often end up with many independent jobs that are logically part of the same workflow. Without grouping, these jobs are scattered across your job history with no way to track or retrieve them together. GroupJobSession solves this by grouping any number of jobs under a single group ID. Key benefits:

Cross-device, cross-provider: submit jobs to different backends (AWS SV1, IonQ, qBraid simulators) within the same group
Unified tracking: all jobs share a group QRN visible in the qBraid dashboard
Aggregated results: retrieve all results at once with group.results()
Lifecycle management: auto-close with TTL, cancellation, completion callbacks

Context Manager

The simplest way to use group jobs. All jobs submitted inside the with block are automatically tagged with the group ID. The group closes when the block exits.

from qbraid.runtime import GroupJobSession, QbraidProvider

provider = QbraidProvider()

bell = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c = measure q;
"""

# All jobs inside this block belong to the same group
with GroupJobSession(name="Bell State Sweep") as group:
    # Submit to different devices within the same group
    sv1 = provider.get_device("aws:aws:sim:sv1")
    job1 = sv1.run(bell, shots=100)

    tn1 = provider.get_device("aws:aws:sim:tn1")
    job2 = tn1.run(bell, shots=100)

    print(f"Group ID: {group.group_id}")
    print(f"Jobs in group: {len(group.jobs)}")

# Group ID: group:abc-123456
# Jobs in group: 2

Manual Open / Close

For interactive workflows like Jupyter notebooks, you can open and close the group manually across multiple cells.

from qbraid.runtime import GroupJobSession, QbraidProvider

provider = QbraidProvider()

# Create and open the group manually
group = GroupJobSession(name="Notebook Experiment")
group.open()

# Cell 2: submit jobs (can be in separate notebook cells)
device = provider.get_device("qbraid:qbraid:sim:qir-sv")
job1 = device.run(circuit_1, shots=100)
job2 = device.run(circuit_2, shots=100)

# Cell 3: close when done submitting
group.close()

Auto-Close with TTL

Set a time-to-live so the group automatically closes after a duration, even if you forget to call close() or your kernel crashes. Defaults to 1 hour (3600s) if not specified.

# Group auto-closes after 60 seconds (default: 3600s / 1 hour)
with GroupJobSession(name="Quick Sweep", max_ttl=60) as group:
    device = provider.get_device("aws:aws:sim:sv1")
    job = device.run(bell, shots=10)
    print(f"TTL: {group.max_ttl}s")

The max_ttl parameter accepts values from 1 to 86400 seconds (24 hours). If not specified, the backend defaults to 3600 seconds (1 hour).

Retrieving Results

After closing a group, retrieve all job results at once. group.results() blocks until every job reaches a terminal state (completed, failed, or cancelled).

with GroupJobSession(name="Result Demo") as group:
    device = provider.get_device("qbraid:qbraid:sim:qir-sv")
    job1 = device.run(bell, shots=100)
    job2 = device.run(bell, shots=100)

# Wait for all jobs and collect results
results = group.results(timeout=300)
print(results)

for job_id, result in results.results.items():
    print(f"{job_id}: {result.data.get_counts()}")

GroupResult(group_id='group:ghi-345678', total=2, successful=2, failed=0)
job:aaa-111: {'00': 48, '11': 52}
job:bbb-222: {'00': 51, '11': 49}

You can also filter results by outcome:

# Only successful results
successful = results.successful()

# Only failed results
failed = results.failed()

Completion Callback

Register a callback that fires automatically when all jobs complete. The callback runs at context exit, after the group is closed.

def analyze(results):
    """Process results when all jobs finish."""
    for job_id, result in results.items():
        counts = result.data.get_counts()
        print(f"{job_id}: {counts}")

with GroupJobSession(name="With Callback") as group:
    device = provider.get_device("qbraid:qbraid:sim:qir-sv")
    device.run(bell, shots=100)
    device.run(bell, shots=100)

    # Callback fires automatically when the context exits
    group.on_all_complete(analyze, timeout=600)

job:ccc-333: {'00': 47, '11': 53}
job:ddd-444: {'00': 50, '11': 50}

Cancellation

Cancel a group and all its non-terminal jobs:

group = GroupJobSession(name="Cancellable")
group.open()

device = provider.get_device("aws:aws:sim:sv1")
job1 = device.run(bell, shots=1000)
job2 = device.run(bell, shots=1000)

# Cancel the entire group and reset the session
group.cancel()

print(group.status())
# GroupStatus.CANCELLED

Batch Jobs

Submit multiple circuits as a single job to a device that supports batched execution. Unlike group jobs, which coordinate independent jobs across devices, batch jobs send all circuits in one request and return a unified result.

Submitting a Batch

Pass a list of programs with as_batch=True to submit them as a single job:

from qiskit import QuantumCircuit
from qbraid.runtime import QbraidProvider

provider = QbraidProvider()
device = provider.get_device("qbraid:equal1:sim:bell-1")

# Define multiple circuits
bell = QuantumCircuit(2, 2)
bell.h(0)
bell.cx(0, 1)
bell.measure([0, 1], [0, 1])

ghz = QuantumCircuit(3, 3)
ghz.h(0)
ghz.cx(0, 1)
ghz.cx(1, 2)
ghz.measure([0, 1, 2], [0, 1, 2])

x_gate = QuantumCircuit(1, 1)
x_gate.x(0)
x_gate.measure(0, 0)

# Submit all three circuits as a single batch job
job = device.run([bell, ghz, x_gate], shots=1000, as_batch=True)
print(type(job))
# <class 'qbraid.runtime.native.job.QbraidJob'>

A batch submission returns a single QbraidJob, not a list. All circuits share the same job ID, device, and shot count.

as_batch=True requires a device that supports batch execution. You can check this via the device profile’s batch_job_support flag. Passing as_batch=True to an unsupported device raises a ValueError.

Retrieving Batch Results

Calling job.result() on a batch job returns a BatchResult object:

result = job.result()
print(type(result))
print(result.num_circuits)

<class 'qbraid.runtime.result.BatchResult'>
3

BatchResult provides two ways to access measurement data: Aggregate access — indexed by circuit position:

# All circuit counts as a list
all_counts = result.data.get_counts()
for i, counts in enumerate(all_counts):
    print(f"Circuit {i}: {counts}")

Circuit 0: {'00': 512, '11': 488}
Circuit 1: {'000': 498, '111': 502}
Circuit 2: {'1': 1000}

Per-circuit access — each circuit’s Result is a full object with its own status and metadata:

for i, circuit_result in enumerate(result.results):
    print(f"Circuit {i}: status={circuit_result.success}, counts={circuit_result.data.get_counts()}")

Circuit 0: status=True, counts={'00': 512, '11': 488}
Circuit 1: status=True, counts={'000': 498, '111': 502}
Circuit 2: status=True, counts={'1': 1000}

BatchResult Properties

Property	Type	Description
`num_circuits`	`int`	Number of circuits in the batch
`results`	`list[Result]`	Per-circuit `Result` objects
`data`	`ResultData`	Aggregated data — `get_counts()` and `get_probabilities()` return lists
`details`	`list[dict]`	Per-circuit metadata (e.g. `compiledOutput`)
`success`	`bool`	Whether the overall job completed successfully
`device_id`	`str`	Device QRN
`job_id`	`str`	Job QRN

Per-Circuit Error Handling

In a batch job, individual circuits can fail while others succeed. Failed circuits carry their own error message, accessible through their per-circuit result:

result = job.result()

for i, circuit_result in enumerate(result.results):
    if not circuit_result.success:
        print(f"Circuit {i} failed: {circuit_result.details.get('statusMsg')}")
    else:
        print(f"Circuit {i}: {circuit_result.data.get_counts()}")

Batch Jobs vs Group Jobs

	Batch Jobs	Group Jobs
Scope	Multiple circuits, one device	Multiple jobs, any device
Submission	`device.run(programs, as_batch=True)`	`GroupJobSession` context
Return type	Single `QbraidJob` → `BatchResult`	Multiple `QbraidJob` → `GroupResult`
Use case	Parameterized circuits, algorithm variants	Cross-device benchmarks, sweeps
Supported devices	Devices with `device.profile.batch_job_support`	All devices

​Single Job Submission

​Group Jobs

​Why Group?

​Context Manager

​Manual Open / Close

​Auto-Close with TTL

​Retrieving Results

​Completion Callback

​Cancellation

​Batch Jobs

​Submitting a Batch

​Retrieving Batch Results

​BatchResult Properties

​Per-Circuit Error Handling

​Batch Jobs vs Group Jobs

Single Job Submission

Group Jobs

Why Group?

Context Manager

Manual Open / Close

Auto-Close with TTL

Retrieving Results

Completion Callback

Cancellation

Batch Jobs

Submitting a Batch

Retrieving Batch Results

BatchResult Properties

Per-Circuit Error Handling

Batch Jobs vs Group Jobs