HubQuantumClient

Part of the Kipu Quantum Hub API SDK reference - see the landing page for installation and Python credential helpers.

Use HubQuantumClient to run jobs and manage sessions. It is the most common entry point for users of the SDK.

Authentication

HubQuantumClient authenticates with a personal access token or a service execution token, sent as the X-Auth-Token request header. Tokens are never cached or refreshed by the SDK itself - the caller provides a valid credential and rotates service execution tokens before they expire.

Python ships optional credential helpers in qhub.api.credentials that read the token from the environment or the shared qhubctl config file (see Python credential helpers). They are not wired into the client constructors automatically; pass the resolved token in via api_key yourself.

The TypeScript SDK does not ship credential helpers; read process.env.KQH_PERSONAL_ACCESS_TOKEN (or your own variable) and pass it via apiKey.

Organization scoping

Most Quantum endpoints accept an X-OrganizationId header to scope the request to a specific organization. HubQuantumClient exposes a dedicated organization_id / organizationId constructor option that sends the header on every request; in TypeScript, individual sub-client methods also accept a per-request override. Construct one client per organization if you need to switch at runtime.

The Python helpers in Python context resolution resolve the id from the qhubctl config file and the environment, but, like credentials, you must feed the resolved id into the client yourself.

Quickstart

Submit a job, wait for it, and fetch the result.

import time

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.jobs import CreateJobRequestInput_AzureIonqSimulator
from qhub.api.quantum.types import AzureIonqJobInputCircuitItem

client = HubQuantumClient(api_key="YOUR_PERSONAL_ACCESS_TOKEN")

job = client.jobs.create_job(
    backend_id="aws.sim.sv1",
    shots=1000,
    input=CreateJobRequestInput_AzureIonqSimulator(
        circuit=[
            AzureIonqJobInputCircuitItem(targets=[0]),
            AzureIonqJobInputCircuitItem(targets=[1], controls=[0]),
        ],
        gateset="qis",
        qubits=2,
    ),
)

while client.jobs.get_job_status(job.id).status in ("PENDING", "RUNNING"):
    time.sleep(2)

print(client.jobs.get_job_result(job.id))

Constructor

Parameter	Required	Description
api_key / apiKey	yes	Personal access token or service execution token; sent as X-Auth-Token.
organization_id / organizationId	no	Value for the X-OrganizationId header; sent on every request from this client.
base_url / baseUrl	no	Overrides both the default environment and environment if supplied.
environment	no	HubQuantumClientEnvironment.DEFAULT (Python) / HubQuantumEnvironment.Default (TypeScript), see Endpoints.
headers	no	Additional headers merged into every request.
timeout / timeoutInSeconds	no	Read timeout in seconds; defaults to 60 when no custom HTTP client is supplied.
max_retries / maxRetries	no	Number of retries for transient failures; defaults to 2.
follow_redirects	no (Python only)	Passed through to httpx.Client; defaults to True.
httpx_client / fetch	no	Inject a preconfigured HTTP client (Python) or fetch implementation (TypeScript).
logging	no	Logger instance or {level, logger, silent} config dict.

Python also ships AsyncHubQuantumClient with the same shape plus an httpx.AsyncClient hook.

from qhub.api.quantum import HubQuantumClient

client = HubQuantumClient(
    api_key="YOUR_PERSONAL_ACCESS_TOKEN",
    organization_id="YOUR_ORGANIZATION_ID",
    timeout=120,
    max_retries=3,
)

Behaviour

• base_url / baseUrl always wins over environment.
• timeout is ignored in Python when a preconfigured httpx_client is supplied; configure the timeout on the injected client instead.
• max_retries applies to transient failures (network errors and 5xx responses); per-request overrides in request_options (Python) or per-call options (TypeScript) take precedence.

Namespaces

HubQuantumClient exposes five sub-clients, lazily instantiated on first access.

Namespace	Purpose
backends	Discover backends and read their configuration and calibration.
sessions	Open, inspect, and close quantum sessions.
jobs	Submit, monitor, retrieve, and cancel jobs (session or not).
workloads	List jobs and sessions as a single paginated stream.
runtime_minutes / runtimeMinutes	Prepaid runtime-minutes allowances of the calling tenant.

Backends

Backends describe the hardware or simulators you can target.

Method	Description
backends.get_backends(provider=?, only_planqk_sdk=?) / backends.getBackends({ provider?, onlyPlanqkSdk? })	List backends, optionally filtered by provider.
backends.get_backend(id) / backends.getBackend(id)	Fetch one backend with full configuration metadata.
backends.get_backend_status(id) / backends.getBackendStatus(id)	Current status (ONLINE, PAUSED, OFFLINE, RETIRED).
backends.get_backend_config(id) / backends.getBackendConfig(id)	Raw backend configuration as a JSON object.
backends.get_backend_calibration(id, effective_at=?) / backends.getBackendCalibration(id, { effectiveAt? })	Calibration, optionally at a historical timestamp.
backends.get_backend_calibration_history(id, from_, to, page=?, size=?, sort=?) / backends.getBackendCalibrationHistory(id, { from, to, page?, size?, sort? })	Page of calibration snapshots archived over a time interval.
backends.get_least_busy_backend(provider, min_qubits=?) / backends.getLeastBusyBackend({ provider, minQubits? })	Backend with the lowest queue size for a provider (IBM-only today).

Sessions

Sessions group jobs on the same backend to amortize provider startup cost.

OPEN ──► ACTIVE ──► DRAINING ──► CLOSED
  │         │
  │         └──► INACTIVE
  └──────────────► ABORTED

UNKNOWN is used for any state the server has not yet resolved (for example, right after creation). DETACHED is final too: the session outlived the credential that reached it, so no measurement can be obtained.

Method	Description
sessions.create_session(backend_id, mode, provider, ttl=?, tags=?, metadata=?, sdk_provider=?)	Open a new session. mode is batch or dedicated; ttl is max lifetime in seconds.
sessions.get_session(id)	Full session record.
sessions.get_session_status(id)	Terse {status} view for polling.
sessions.get_session_jobs(id)	Jobs attached to this session.
sessions.update_session_state(id, accept_jobs=bool)	Stop or resume accepting new jobs.
sessions.close_session(id)	Close the session; subsequent submissions are rejected.

TypeScript exposes the same methods in camelCase (sessions.createSession({ backend_id, mode, provider, ttl?, tags?, metadata?, sdk_provider? }), sessions.getSession(id), sessions.getSessionStatus(id), sessions.getSessionJobs(id), sessions.updateSessionState(id, { accept_jobs }), sessions.closeSession(id)).

Example - batch session on AWS Braket

session = client.sessions.create_session(
    backend_id="aws.sim.sv1",
    mode="batch",
    provider="AWS",
    ttl=900,
)

try:
    for i in range(5):
        client.jobs.create_job(
            backend_id="aws.sim.sv1",
            shots=500,
            input=my_input,
            session_id=session.id,
            tags=[f"iter-{i}"],
        )
finally:
    client.sessions.close_session(session.id)

Jobs

PENDING ──► RUNNING ──► COMPLETED
    │          │
    │          ├──► FAILED
    │          ├──► CANCELLING ──► CANCELLED
    │          └──► ABORTED
    └──► CANCELLING ──► CANCELLED

UNKNOWN covers states the server has not yet resolved. Terminal states are COMPLETED, FAILED, ABORTED, CANCELLED, and DETACHED. DETACHED means the job outlived the credential that reached it, so no result will ever arrive.

Method	Description
jobs.search_jobs(page=?, size=?, sort=?, service_execution_id=?)	Paginated listing, optionally filtered by service execution.
jobs.create_job(backend_id, shots, input, name=?, input_format=?, input_params=?, tags=?, session_id=?, sdk_provider=?)	Submit a new job.
jobs.get_job(id)	Full job record.
jobs.get_job_status(id)	Terse {status} view for polling.
jobs.get_job_result(id)	Parsed result body (JSON).
jobs.get_normalized_job_result(id)	Provider-independent view of the result, one typed union per PUB.
jobs.get_normalized_job_memory(id)	Per-shot measurement values as Qiskit hex strings.
jobs.get_job_result_stream(id)	Stream the result file in chunks (Python iterator / Node stream).
jobs.get_job_input(id)	Input file (string).
jobs.get_normalized_job_input(id)	Provider-independent QASM view of the input, one entry per PUB.
jobs.get_job_calibration(id)	Calibration snapshot captured at execution time.
jobs.cancel_job(id)	Request cancellation; state transitions to CANCELLING.

TypeScript exposes the same methods in camelCase (jobs.searchJobs({ page?, size?, sort?, serviceExecutionId? }), jobs.createJob({ ... }), jobs.getJob(id), and so on).

A second family of methods with the service_execution_ prefix (Python) / ServiceExecution suffix (TypeScript) addresses jobs and sessions that belong to a managed service execution - for example, jobs.get_service_execution_job(service_execution_id, job_id) / jobs.getServiceExecutionJob(serviceExecutionId, jobId), jobs.close_service_execution_session(...) / jobs.closeServiceExecutionSession(...), jobs.cancel_service_execution_job(...) / jobs.cancelServiceExecutionJob(...), and so on. Use the plain methods when you created the job yourself; use the service-execution-scoped methods when the job was created by a managed service on your behalf.

Per-PUB views

A job carries an ordered list of one or more PUBs (Primitive Unified Blocs), and both normalized views - get_normalized_job_input and get_normalized_job_result - serve one entry per PUB in submission order. A single-PUB job, which is every job that does not submit a PUB list, serves a list of length one.

The two views are index-aligned: get_normalized_job_input(...).pubs[i] is the submission that produced get_normalized_job_result(...).pubs[i]. That is what makes it safe to label one PUB's numbers with its own observables. A PUB whose payload carries no normalizable result keeps its index as an unmapped entry rather than being dropped, so the alignment holds even then. A FAILED job is the one exception: its result view serves a single error entry whatever its PUB count, so pair the two views by index only on a job that reached COMPLETED.

The raw get_job_input and get_job_result endpoints are unaffected and stay byte-identical.

Service-execution-scoped methods

These mirror the plain job and session methods but address workloads owned by a managed service execution. Use them when the job or session was created by a managed service on your behalf.

Method	Description
jobs.get_service_execution_workloads(service_execution_id, page=?, size=?, sort=?) / jobs.getServiceExecutionWorkloads(serviceExecutionId, { page?, size?, sort? })	Paginated workloads (jobs + sessions) running inside the execution.
jobs.get_service_execution_session(service_execution_id, session_id) / jobs.getServiceExecutionSession(serviceExecutionId, sessionId)	Fetch one session inside an execution.
jobs.get_service_execution_session_status(service_execution_id, session_id) / jobs.getServiceExecutionSessionStatus(serviceExecutionId, sessionId)	Status of a session inside an execution.
jobs.get_service_execution_session_jobs(service_execution_id, session_id) / jobs.getServiceExecutionSessionJobs(serviceExecutionId, sessionId)	Jobs belonging to a session inside an execution.
jobs.update_service_execution_session_state(service_execution_id, session_id, accept_jobs=bool) / jobs.updateServiceExecutionSessionState(serviceExecutionId, sessionId, { accept_jobs })	Drain or resume a session inside an execution.
jobs.close_service_execution_session(service_execution_id, session_id) / jobs.closeServiceExecutionSession(serviceExecutionId, sessionId)	Close a session inside an execution.
jobs.get_service_execution_job(service_execution_id, job_id) / jobs.getServiceExecutionJob(serviceExecutionId, jobId)	Fetch one job inside an execution.
jobs.get_service_execution_job_status(service_execution_id, job_id) / jobs.getServiceExecutionJobStatus(serviceExecutionId, jobId)	Status-only view for the same job.
jobs.get_service_execution_job_input(service_execution_id, job_id) / jobs.getServiceExecutionJobInput(serviceExecutionId, jobId)	Input JSON for the job.
jobs.get_service_execution_normalized_job_input(service_execution_id, job_id) / jobs.getServiceExecutionNormalizedJobInput(serviceExecutionId, jobId)	Provider-independent QASM view of the job's input.
jobs.get_service_execution_job_result_stream(service_execution_id, job_id) / jobs.getServiceExecutionJobResultStream(serviceExecutionId, jobId)	Stream the job's result file.
jobs.get_service_execution_normalized_job_result(service_execution_id, job_id) / jobs.getServiceExecutionNormalizedJobResult(serviceExecutionId, jobId)	Provider-independent view of the job's result, one entry per PUB.
jobs.get_service_execution_job_calibration(service_execution_id, job_id) / jobs.getServiceExecutionJobCalibration(serviceExecutionId, jobId)	Calibration snapshot for the job.
jobs.cancel_service_execution_job(service_execution_id, job_id) / jobs.cancelServiceExecutionJob(serviceExecutionId, jobId)	Cancel the job.

workloads = client.jobs.get_service_execution_workloads(
    service_execution_id=execution_id,
    page=0,
    size=50,
    sort="created_at,desc",
)
for w in workloads.content or []:
    print(w.id, w.type, w.status)

job = client.jobs.get_service_execution_job(execution_id, job_id)

Return shapes mirror the plain methods: PageResponseWorkloadResponse for the workload listing, Job for single-job lookups, Session for single-session lookups, SessionStatusResponse and JobStatusResponse for the status-only variants, NormalizedJobInput and NormalizedJobResult for the normalized views, Iterator[bytes] / ReadableStream<Uint8Array> for the result stream, Dict[str, Any] / Record<string, unknown> for the input file, CalibrationResponse? for calibration, and no body for cancel and close.

Polling for completion

import time

TERMINAL = {"COMPLETED", "FAILED", "ABORTED", "CANCELLED", "DETACHED"}

def wait(job_id: str, poll_interval: float = 2.0) -> str:
    while True:
        status = client.jobs.get_job_status(job_id).status
        if status in TERMINAL:
            return status
        time.sleep(poll_interval)

final = wait(job.id)
if final == "COMPLETED":
    result = client.jobs.get_job_result(job.id)

Streaming the result file

Large results are better consumed as a byte stream; the *_stream / *Stream variants hand you chunks rather than parsing the full JSON into memory.

with open("result.json", "wb") as out:
    for chunk in client.jobs.get_job_result_stream(job.id):
        out.write(chunk)

Workloads

workloads.get_workloads(...) / workloads.getWorkloads({ ... }) returns a single paginated list mixing jobs and sessions, tagged with a type discriminator (JOB or SESSION). A SESSION entry also carries mode ("batch" or "dedicated"), the same execution mode as Session; a JOB entry leaves it unset. Use it when you want a uniform "show me everything running" view; otherwise reach for jobs.search_jobs or list sessions individually.

Runtime minutes

Prepaid runtime-minutes pools let a tenant buy backend time up front instead of paying per job.

Method	Description
runtime_minutes.get_runtime_minutes() / runtimeMinutes.getRuntimeMinutes()	List the calling tenant's pools, read live from the provider.

Advanced usage

Running N jobs in parallel

import asyncio

from qhub.api.quantum import AsyncHubQuantumClient

async def run_batch(inputs):
    client = AsyncHubQuantumClient(api_key="YOUR_TOKEN")
    jobs = await asyncio.gather(*(
        client.jobs.create_job(backend_id="aws.sim.sv1", shots=1000, input=i)
        for i in inputs
    ))
    return [j.id for j in jobs]

Polling with exponential backoff

import random, time

def wait_with_backoff(job_id, initial=1.0, cap=30.0):
    delay = initial
    while True:
        status = client.jobs.get_job_status(job_id).status
        if status in ("COMPLETED", "FAILED", "ABORTED", "CANCELLED", "DETACHED"):
            return status
        time.sleep(delay + random.uniform(0, delay * 0.1))
        delay = min(delay * 2, cap)

Fetch passthrough (TypeScript)

The TypeScript client exposes client.fetch(input, init?, requestOptions?), which reuses the client's base URL, auth provider, retry policy, and logging to call an endpoint that does not yet have a typed wrapper. Python does not ship a public equivalent; for that case, use client._client_wrapper at your own risk or drop down to httpx directly.

Endpoints

Default base URL	Override
https://api.hub.kipu-quantum.com/quantum	base_url=... / baseUrl: ..., or environment=HubQuantumClientEnvironment.DEFAULT (Python) / environment: HubQuantumEnvironment.Default (TypeScript).

To target a staging or on-prem deployment, set base_url / baseUrl at construction time.

Errors

HTTP errors are raised as typed exceptions. All Python errors extend ApiError (in qhub.api.quantum.core.api_error); all TypeScript errors extend HubQuantumError.

Status	Python class	TypeScript class	Meaning
400	BadRequestError	BadRequestError	Malformed request.
401	UnauthorizedError	UnauthorizedError	Missing or invalid credentials.
403	ForbiddenError	ForbiddenError	Authenticated but not permitted.
404	NotFoundError	NotFoundError	Resource does not exist.
422	UnprocessableEntityError	UnprocessableEntityError	Validation failure on the request body, or a job whose input cannot be rendered as QASM (get_normalized_job_input).
500	InternalServerError	InternalServerError	Server-side failure.

Other failure modes:

• Auth misconfiguration (TypeScript) - constructing HubQuantumClient without apiKey throws HubQuantumError with message "Please provide 'apiKey' when initializing the client".
• Timeouts - hitting timeoutInSeconds raises HubQuantumTimeoutError in TypeScript; in Python, timeouts surface as the underlying httpx.TimeoutException.
• Missing base URL - passing environment=None and omitting base_url to the Python constructor raises Exception("Please pass in either base_url or environment to construct the client").

All HTTP error instances expose status_code, headers, and body (Python) / statusCode, rawResponse, and body (TypeScript) so you can inspect the server's response detail.

from qhub.api.quantum.errors import NotFoundError, UnauthorizedError

try:
    client.jobs.get_job("does-not-exist")
except NotFoundError as e:
    print("missing", e.status_code, e.body)
except UnauthorizedError:
    print("refresh your token")

Reference

Job

Field	Type	Description
id	str?	Unique job identifier.
name	str?	Optional human-readable name.
backend_id	str?	Backend the job runs on.
provider	JobProvider?	Provider enum (see below).
provider_job_id	str?	Provider-assigned job id.
input_params	JsonNode?	Backend-specific parameters supplied at submission.
input_format	JobInputFormat?	Format of the submitted input.
tags	List[str]?	Free-form tags.
status	JobStatus?	See Jobs.
created_at / started_at / ended_at	str? (ISO 8601)	Lifecycle timestamps.
usage_time_millis	int?	Provider-reported usage time, in milliseconds.
runtime	int?	Deprecated alias of usage_time_millis.
shots	int?	Number of shots.
session_id	str?	Parent session, if any.
sdk_provider	JobSdkProvider?	SDK that produced the input.

Session

Field	Type	Description
id	str?	Unique session identifier.
backend_id	str?	Backend the session runs on.
provider	SessionProvider?	Provider enum.
status	SessionStatus?	See Sessions.
mode	SessionMode?	"batch" or "dedicated".
created_at / started_at / closed_at / expires_at	str?	Lifecycle timestamps.
usage_time_millis	int?	Billed usage time.
provider_id	str?	Provider-assigned session id.
tags	List[str]?	Free-form tags.
metadata	JsonNode?	Free-form metadata supplied at creation.
sdk_provider	SessionSdkProvider?	SDK that opened the session.
final	bool?	True once the session is in a terminal state.
final_not_aborted	bool?	True when the session reached a terminal state without being aborted.

Backend

Field	Type	Description
id	str?	Backend identifier (e.g. aws.sim.sv1).
internal_id	str?	Hub-internal id.
provider	BackendProvider?	AZURE, AWS, IBM, QRYD, QUDORA, QUANDELA, IQM, KIPU.
hardware_provider	BackendHardwareProvider?	Actual hardware vendor.
name / display_name	str?	Machine-readable / human-readable name.
type	BackendType?	QPU, SIMULATOR, ANNEALER, UNKNOWN.
technology	BackendTechnology?	SUPERCONDUCTING, TRAPPED_ION, PHOTONIC, NEUTRAL_ATOMS, UNKNOWN.
queue_size	int?	Current queue length.
updated_at	str?	Last-updated timestamp.
access_type	BackendAccessType?	How access is billed (e.g. pay-per-use).
documentation	Documentation?	Doc links and per-SDK guidance.
configuration	Configuration?	Native gate set, qubit count, supported formats.
availability	List[AvailabilityTimes]?	Operating windows.
costs	List[Cost]?	Pricing per provider.
has_calibration	bool?	True if calibration data is available.
free_of_charge	bool?	True if execution is not billed.

CalibrationResponse

Returned by backends.get_backend_calibration, jobs.get_job_calibration and their service-execution variant, and paged by backends.get_backend_calibration_history.

Field	Type	Description
backend_id	str	Backend the calibration belongs to.
calibrated_at	datetime / string (ISO 8601)	Instant the calibration was effective on the backend.
calibration	GateBasedCalibration | QueraAquilaCalibration	Gate-based for every QPU but QuEra Aquila, which keeps its own analog shape.

calibration is discriminated by type: gate_based for GateBasedCalibration, quera_aquila for QueraAquilaCalibration. Tell the members apart with calibration.type, which also narrows the union in TypeScript. A payload whose fields do not match the member its type names fails to parse instead of resolving to the other member.

Units are the provider's natural ones at full precision: coherence times in microseconds, durations in nanoseconds, qualities as errors in [0, 1], where 0 is perfect. A measured field is absent where the provider reports nothing for it.

GateBasedCalibration:

Field	Type	Description
type	"gate_based"	Discriminator of the calibration union.
medians	CalibrationMedians	Backend-wide medians over the operational qubits and pairs that report each value.
qubits	List[QubitCalibration]	One entry per qubit, by ascending index. Empty where the provider reports only medians.
qubit_pairs	List[QubitPairCalibration]	One entry per coupled pair. Empty where the provider reports only medians.
native_gate_calibration	str?	Where to fetch Rigetti's pulse-level native gate calibration; absent on every other provider.

QubitCalibration:

Field	Type	Description
qubit	int	Index of the qubit, the one a circuit addresses.
name	str?	Name the provider gives the qubit, where it names them.
operational	bool	False when the provider marks the qubit as dead. A dead qubit is left out of every median.
t1_us / t2_us / t2_echo_us	float?	T1, T2 and spin-echo T2 in microseconds; each has a *_std standard deviation.
readout_error	float?	Probability that a measurement returns the wrong bit; has a readout_error_std.
readout_length_ns / reset_length_ns	float?	Measurement and reset durations in nanoseconds.
prob_meas0_prep1 / prob_meas1_prep0	float?	Probability of measuring 0 after preparing 1, and 1 after preparing 0.
gates	Dict[str, GateCalibration]	Single-qubit gates keyed by the provider's gate name, or by one_qubit where the provider reports one figure for all of them.

QubitPairCalibration is {qubits: List[int], gates: Dict[str, GateCalibration]}: the two qubit indices ascending, and the two-qubit gates keyed by the provider's gate name, or by two_qubit where the provider reports one figure for all of them. A pair appears once; a directional gate keeps its direction in the gate name.

GateCalibration is {operational: bool, error: float?, error_std: float?, length_ns: float?}; operational is false when the provider marks the gate as dead, and a dead gate is left out of its gate median.

CalibrationMedians carries the median of t1_us, t2_us, t2_echo_us, readout_error, readout_length_ns and reset_length_ns, each with its *_std where it has one, plus spam_error for providers that report state preparation and measurement error, and gates: the median per gate name over every operational gate of an operational qubit or pair; a median entry is always operational.

QueraAquilaCalibration is {type: "quera_aquila", lattice?, rydberg?, performance?}, each of the last three the provider's own JSON object.

NormalizedJobResult

Returned by jobs.get_normalized_job_result / jobs.getNormalizedJobResult.

Field	Type	Description
pubs	List[NormalizedPubResult]	One entry per submitted PUB, in submission order.

See Per-PUB views for the ordering and index-alignment guarantee.

NormalizedMemoryResult

Returned by jobs.get_normalized_job_memory / jobs.getNormalizedJobMemory.

Field	Type	Description
memory	List[str]? / string[]?	Per-shot measurement values as Qiskit hex strings, one per shot.
qubits	int? / number?	Number of qubits measured.
shots	int? / number?	Total number of measurement shots.

NormalizedPubResult

One PUB's measurement result, discriminated by type. Every member carries type; every member except error also carries index and name; the remaining fields belong to one member each.

type	Member	Produced by
counts	NormalizedCountsResult	A sampled backend - real measurement tallies, never derived.
probabilities	NormalizedProbabilitiesResult	A state-vector or probability-native backend.
expectation_values	NormalizedExpectationValuesResult	An estimator primitive - expectation values with their uncertainties.
error	NormalizedErrorResult	A FAILED job, wrapping the error envelope verbatim.
unmapped	NormalizedUnmappedResult	A PUB whose payload carries no normalizable result - a placeholder holding that PUB's index.

In Python each member is a distinct class (NormalizedPubResult_Counts, NormalizedPubResult_ExpectationValues, ...); in TypeScript they are members of the HubQuantum.NormalizedPubResult namespace (NormalizedPubResult.Counts, NormalizedPubResult.ExpectationValues, ...).

Fields on every member except error:

Field	Type	Description
index	int	0-based position of this PUB in the submission, the same position as its entry in the normalized input view. Always present.
name	str?	Name of this PUB as the SDK captured it. A label, not a key: names can repeat. Absent when the PUB has no name or the job's normalized input is not archived.

The error member describes the job, not a PUB, so it carries neither field.

The unmapped member carries one field of its own, reason (str?), which says why this PUB has no normalized result. It is served rather than dropped so that a later PUB can never slide into an earlier one's index and be read against that PUB's observables. A FAILED job serves its one error envelope as a single entry, not one per submitted PUB.

Bitstring keys in the counts and probabilities members use Qiskit little-endian order - clbit 0 is the rightmost character.

counts:

Field	Type	Description
counts	Dict[str, int]?	Measurement tallies keyed by bitstring.
shots	int?	Total number of measurement shots.
qubits	int?	Number of qubits measured.
key_format	str?	Always "bitstring" today; reserved for non-qubit backends.

probabilities:

Field	Type	Description
probabilities	Dict[str, float]?	Probabilities keyed by bitstring.
qubits	int?	Number of qubits.
truncated	bool?	True when the entry cap dropped real probability mass.
key_format	str?	Always "bitstring" today; reserved for non-qubit backends.

expectation_values:

Field	Type	Description
shape	List[int]	Shape the flat lists below belong to. Not derivable from the value count, so it is always sent.
values	List[float]	Expectation values, row-major over shape.
stds	List[float]	Standard error of the mean over the per-twirl values, one per expectation value.
ensemble_stds	List[float]?	Standard error over all shots pooled as one ensemble. Coincides with stds when twirling is off.
observable_index	List[int]?	Index into observables for each expectation value, so no caller reimplements the provider's array broadcasting.
observables	List[NormalizedObservable]?	The observables measured. Absent when the job's input was not archived.
parameter_values	List[List[float]]?	Parameter values bound to the circuit, one list per parameter set, capped at the first 256 sets. Parameter names are not recoverable.
run_context	EstimatorRunContext?	The settings the run resolved for itself.

error:

Field	Type	Description
error	Dict[str, Any]?	The error envelope, verbatim.

NormalizedJobInput

Returned by jobs.get_normalized_job_input / jobs.getNormalizedJobInput.

Field	Type	Description
format	"openqasm.v2" | "openqasm.v3"	Declared OpenQASM dialect of every entry's qasm.
pubs	List[NormalizedPub]	One entry per submitted PUB, in submission order.

The contract guarantees QASM text plus its declared dialect, never a specific one - no V2-to-V3 transformation happens anywhere. Every entry renders the submitted circuit: the executed hardware-native circuit is built on the device downstream and is not accessible, so the view makes no transpile-stage claim. QHub-rendered QASM is for display and may carry // markers for operations with no OpenQASM 3 representation; it is never forwarded to the provider.

NormalizedPub

One PUB of a submission: the executable unit of circuit plus its optional observables, parameter values and shots.

Field	Type	Description
qasm	str	OpenQASM source text of this PUB's circuit, in the view's format dialect.
name	str?	Name of the PUB as the SDK captured it, for example "pub-0".
observables	List[NormalizedObservable]?	Observables this PUB measures. Absent for a sampler PUB and for any submission whose observables are not readable.
parameter_values	List[List[float]]?	One row per parameter set bound to this PUB's circuit, in sweep order, capped at the first 256 sets. Parameter names are not recoverable.
shots	int?	Effective shots for this PUB: its own override where the submission carries one, else the job-level default.

An estimator PUB carries no shots: a precision drives it, so no shot count is knowable.

NormalizedObservable

Field	Type	Description
pattern	str?	Readable label: each term's Pauli string reversed to qubit-0-first order and stripped of identities, terms joined by " + " and elided past the eighth. Carries no qubit indices - it is a shape at a glance, and terms[].qubits is where the indices live.
num_qubits	int?	Width of the layout the terms were applied to.
term_count	int?	Number of Pauli terms in this observable, counting any the pattern elided.
terms	List[ObservableTerm]?	Every term with its qubit indices and coefficient, so nothing pattern drops is lost.

ObservableTerm is {pauli: str?, qubits: List[int]?, coefficient: float?}. Terms are sparse: pauli carries only the non-identity factors, and pauli[i] acts on qubits[i]. Indices ascend and pauli is ordered to match, so the little-endian order of the submitted full-width string is already resolved - a two-character pauli on a 156-qubit device is a two-qubit term, not a truncated one. num_qubits carries the width the dropped identities occupied, which is what Qiskit's SparsePauliOp.from_sparse_list(terms, num_qubits=N) needs to rebuild the observable.

EstimatorRunContext

How the expectation values were produced. These are the values the provider resolved, not necessarily ones the submitter chose - a submission carrying no options at all still runs with readout mitigation on. Each field is absent when the provider's result metadata did not report it.

Field	Type	Description
target_precision	float?	Standard error the run aimed for on each expectation value. The provider default is 0.015625.
num_randomizations	int?	Pauli twirling randomizations the shots were split across, and so the sample size behind stds.
measure_mitigation	bool?	Whether readout error mitigation (TREX) was applied. Mitigated values can fall outside the observable's physical range.
zne_mitigation	bool?	Whether zero-noise extrapolation was applied. ZNE inflates stds far beyond the shot-noise scale.
pec_mitigation	bool?	Whether probabilistic error cancellation was applied.

RuntimeMinutesResponse

Returned by runtime_minutes.get_runtime_minutes / runtimeMinutes.getRuntimeMinutes.

Field	Type	Description
allowances	List[RuntimeMinutesAllowance]?	One entry per prepaid pool.

RuntimeMinutesAllowance

One prepaid runtime-minutes pool.

Field	Type	Description
id	str? / string?	Allowance identifier.
provider	RuntimeMinutesAllowanceProvider?	Cloud provider exposing the backends the pool pays for.
backend_ids	List[str]? / string[]?	Backends the pool applies to.
allocated_seconds	int? / number?	Seconds bought.
consumed_seconds	int? / number?	Seconds already spent.
remaining_seconds	int? / number?	Seconds left.
limit_reached	bool? / boolean?	True once the pool is exhausted.

Pagination wrappers

All paginated endpoints return a PageResponse* object with the shape {content: List[T]?, page: int?, size: int?, total_elements: int?, total_pages: int?}. page is zero-based.

Enums

• JobStatus - UNKNOWN | PENDING | ABORTED | RUNNING | COMPLETED | FAILED | CANCELLING | CANCELLED | DETACHED
• SessionStatus - UNKNOWN | ABORTED | OPEN | ACTIVE | INACTIVE | DRAINING | CLOSED | DETACHED
• BackendStateInfoStatus - UNKNOWN | ONLINE | PAUSED | OFFLINE | RETIRED (returned by backends.get_backend_status / backends.getBackendStatus).
• SessionMode / WorkloadResponseMode - batch | dedicated
• JobInputFormat - OPEN_QASM_V1 | OPEN_QASM_V2 | OPEN_QASM_V3 | QIR_V1 | BRAKET_OPEN_QASM_V3 | BRAKET_AHS_PROGRAM | IONQ_CIRCUIT_V1 | QISKIT_QPY | QOQO | PERCEVAL | IQM_JOB_INPUT_V1
• JobProvider / SessionProvider / WorkloadResponseProvider - AZURE | AWS | IBM | QRYD | QUDORA | QUANDELA | IQM | KIPU
• BackendProvider - AZURE | AWS | IBM | QRYD | QUDORA | QUANDELA | IQM | KIPU
• BackendHardwareProvider - IONQ | RIGETTI | OQC | AWS | AZURE | IBM | QUERA | IQM | QUDORA | QUANTINUUM | QUANDELA | KIPU
• JobSdkProvider / SessionSdkProvider / WorkloadResponseSdkProvider - QISKIT | BRAKET | PERCEVAL | CLIENT
• BackendType - QPU | SIMULATOR | ANNEALER | UNKNOWN
• BackendTechnology - SUPERCONDUCTING | TRAPPED_ION | PHOTONIC | NEUTRAL_ATOMS | UNKNOWN
• WorkloadResponseType - JOB | SESSION
• RuntimeMinutesAllowanceProvider - AZURE | AWS | IBM | QRYD | QUDORA | QUANDELA | IQM | KIPU | AQT

Field casing

Quantum-API DTOs are snake_case in both languages (backend_id, created_at) - the generator preserves the wire casing for this API in TypeScript. TypeScript method arguments themselves use camelCase (sessionId, serviceExecutionId), but request-body shapes follow the DTO casing above.

Python reference

Sessions

client.sessions.create_session(...) -> Session

Description

Create a new quantum session that groups related quantum jobs on a shared backend. Sessions reserve backend resources so subsequent jobs in the session run with reduced queue latency. Prefer a session when submitting multiple related jobs to the same backend; otherwise submit standalone jobs via createJob. The session remains open until explicitly closed (closeSession) or its ttl expires. Returns 422 if the selected backend does not support sessions.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.sessions.create_session(
    backend_id="aws.sim.sv1",
    mode="batch",
    provider="AZURE",
)

Parameters

backend_id: str — Unique backend identifier

mode: CreateSessionRequestMode — Execution mode of a quantum session. batch runs queued jobs without reserving the backend between them; dedicated keeps the backend reserved for the session's lifetime, reducing inter-job latency at higher cost.

provider: CreateSessionRequestProvider — Quantum cloud provider exposing the backend. Distinct from HardwareProvider — a hardware vendor can be offered via multiple clouds.

ttl: typing.Optional[int] — Maximum Time-to-live for the session in seconds

metadata: typing.Optional[typing.Dict[str, typing.Any]]

sdk_provider: typing.Optional[CreateSessionRequestSdkProvider] — Client-side SDK used to submit the workload. QISKIT and BRAKET indicate the workload was submitted through the qhub-quantum SDK via its provider-native integration of the same name. CLIENT indicates direct submission via the API (no qhub-quantum SDK in between).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sessions.get_session(...) -> Session

Description

Get a quantum session's details.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.sessions.get_session(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sessions.close_session(...)

Description

Close a quantum session and release its reserved backend resources. Jobs already submitted to the session are left to complete; no new jobs can be submitted once the session is closed. Idempotent: closing an already-closed session has no effect. To stop accepting new jobs without aborting the session, call updateSessionState with accept_jobs=false instead (DRAINING).

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.sessions.close_session(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sessions.update_session_state(...) -> Session

Description

Update a quantum session's state to control job acceptance.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.sessions.update_session_state(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    accept_jobs=False,
)

Parameters

id: str — Unique session identifier

request: SessionStateUpdateRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sessions.get_session_status(...) -> SessionStatusResponse

Description

Get a quantum session's status.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.sessions.get_session_status(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sessions.get_session_jobs(...) -> Job

Description

Get all quantum jobs belonging to a session.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.sessions.get_session_jobs(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Jobs

client.jobs.search_jobs(...) -> PageResponseJob

Description

Get quantum jobs with pagination.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.search_jobs(
    page=1,
    size=1,
    sort=[
        "sort"
    ],
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

page: typing.Optional[int] — Zero-based page index (0..N)

size: typing.Optional[int] — The size of the page to be returned

sort: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

service_execution_id: typing.Optional[str] — Unique service execution identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.create_job(...) -> Job

Description

Submit a new quantum job for asynchronous execution on a quantum backend. A job can run standalone or, when sessionId is provided, within an open session to share a priority slot on the backend. Execution is asynchronous: the returned job starts non-terminal — poll getJobStatus until it reaches a terminal state (COMPLETED, FAILED, CANCELLED, ABORTED, DETACHED), then retrieve measurement results via getJobResult.

Usage

from qhub.api.quantum import HubQuantumClient, AqtJobInputPayload, AqtJobInputPayloadCircuitsItem
from qhub.api.quantum.environment import HubQuantumClientEnvironment
from qhub.api.quantum.jobs import CreateJobRequestInput_AqtQpuIbex

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.create_job(
    backend_id="aws.sim.sv1",
    shots=1000,
    input=CreateJobRequestInput_AqtQpuIbex(
        job_type="quantum_circuit",
        payload=AqtJobInputPayload(
            circuits=[
                AqtJobInputPayloadCircuitsItem(
                    repetitions=100,
                    number_of_qubits=2,
                    quantum_circuit=[
                        {
                            "operation": "RZ",
                            "qubit": 0,
                            "phi": 0.5
                        },
                        {
                            "operation": "R",
                            "qubit": 1,
                            "phi": 0.5,
                            "theta": 1
                        },
                        {
                            "operation": "RXX",
                            "qubits": [0, 1],
                            "theta": 0.5
                        },
                        {
                            "operation": "MEASURE"
                        }
                    ],
                )
            ],
        ),
    ),
)

Parameters

backend_id: str — Unique backend identifier

shots: int — Number of shots to execute

input: CreateJobRequestInput — Backend-specific job input. The format depends on the backend the job is executed on.

name: typing.Optional[str] — Optional name for the job

input_format: typing.Optional[CreateJobRequestInputFormat] — Format of a quantum job's input circuit. Must match the target backend's supportedInputFormats. OpenQASM flavors cover most gate-based backends; QIR is used for hardware-agnostic IR; provider-specific formats (braket., iqm., ionq.*, qiskit, qoqo, perceval) target a single backend family.

input_params: typing.Optional[CreateJobRequestInputParams] — Backend-specific job input parameters. The supported parameters depend on the backend the job is executed on.

qasm: typing.Optional[QasmCircuit]

tags: typing.Optional[typing.List[str]] — Set of tags to identify or categorize the job

session_id: typing.Optional[str] — Unique session identifier

sdk_provider: typing.Optional[CreateJobRequestSdkProvider] — Client-side SDK used to submit the workload. QISKIT and BRAKET indicate the workload was submitted through the qhub-quantum SDK via its provider-native integration of the same name. CLIENT indicates direct submission via the API (no qhub-quantum SDK in between).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_session(...) -> Session

Description

Get the details of a quantum session running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_session(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    session_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

session_id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.close_service_execution_session(...)

Description

Close a quantum session running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.close_service_execution_session(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    session_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

session_id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.update_service_execution_session_state(...) -> Session

Description

Update the state of a quantum session running within a service execution (accept or reject jobs).

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.update_service_execution_session_state(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    session_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    accept_jobs=False,
)

Parameters

service_execution_id: str — Unique service execution identifier

session_id: str — Unique session identifier

request: SessionStateUpdateRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_workloads(...) -> PageResponseWorkloadResponse

Description

Get quantum workloads (jobs and sessions) running within a specific service execution with pagination.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_workloads(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    page=1,
    size=1,
    sort=[
        "sort"
    ],
)

Parameters

service_execution_id: str — Unique service execution identifier

page: typing.Optional[int] — Zero-based page index (0..N)

size: typing.Optional[int] — The size of the page to be returned

sort: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_session_status(...) -> SessionStatusResponse

Description

Get the status of a quantum session running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_session_status(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    session_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

session_id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_session_jobs(...) -> Job

Description

Get all jobs belonging to a quantum session running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_session_jobs(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    session_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

session_id: str — Unique session identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_job(...) -> Job

Description

Get the details of a quantum job running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_job(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    job_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.cancel_service_execution_job(...)

Description

Cancel the execution of a quantum job running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.cancel_service_execution_job(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    job_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_job_status(...) -> JobStatusResponse

Description

Get the status of a quantum job running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_job_status(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    job_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_normalized_job_result(...) -> typing.Optional[NormalizedJobResult]

Description

Get a provider-independent, normalized view of the measurement results of a quantum job running within a service execution. The response is a discriminated union by 'type': 'counts' for real measurement tallies from sampled backends, 'probabilities' for state-vector-derived distributions, 'error' for a FAILED job (the common error envelope). All bitstring keys use Qiskit little-endian order (clbit 0 is the rightmost character). The normalized view is defined only for gate-based measurement results; backends whose computing paradigm does not produce gate-based counts or probabilities (e.g. photonic, neutral-atom) return 204, as do result shapes with no normalized mapping. Only valid once the job has reached a terminal result state (getServiceExecutionJobStatus returns COMPLETED or FAILED); calling this on a job that has not yet completed returns 404. The raw getServiceExecutionJobResultStream endpoint is unaffected and stays byte-identical.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_normalized_job_result(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    job_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_job_result_stream(...) -> typing.Iterator[bytes]

Description

Get the result of a quantum job running within a service execution as a JSON file. On success the file holds the provider-native result verbatim - the shape varies by backend. Use getServiceExecutionNormalizedJobResult for a provider-independent view.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_job_result_stream(
    service_execution_id="serviceExecutionId",
    job_id="jobId",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_job_input(...) -> typing.Dict[str, typing.Any]

Description

Get the input.json of a quantum job running within a service execution. Returns the provider-native input verbatim - the shape varies by backend. Use getServiceExecutionNormalizedJobInput for a provider-independent QASM view.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_job_input(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    job_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_normalized_job_input(...) -> NormalizedJobInput

Description

Get the provider-independent QASM view of a quantum job's input, for a job running within a service execution. Returns 422 when the input cannot be rendered as QASM. The raw getServiceExecutionJobInput endpoint is unaffected and stays byte-identical.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_normalized_job_input(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    job_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_service_execution_job_calibration(...) -> typing.Optional[CalibrationResponse]

Description

Get the calibration for a quantum job running within a service execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_service_execution_job_calibration(
    service_execution_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
    job_id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

service_execution_id: str — Unique service execution identifier

job_id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job(...) -> Job

Description

Get the full details of a quantum job, including status, timestamps, backend, and session affiliation. Fields populated depend on the job's lifecycle stage (e.g. execution timestamps appear once the job starts running). Use getJobStatus when only the status is needed (lighter and cheaper to poll), and getJobResult once the job reaches a terminal state to retrieve measurement results.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_job(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.cancel_job(...)

Description

Cancel the execution of a quantum job.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.cancel_job(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_status(...) -> JobStatusResponse

Description

Get just the current lifecycle status of a quantum job. Cheaper than getJob when polling. Non-terminal statuses (PENDING, RUNNING, CANCELLING) indicate the job is still being processed; terminal statuses (COMPLETED, FAILED, CANCELLED, ABORTED) indicate the job has finished and getJobResult can be called; DETACHED is terminal too, but means the job outlived the credential that reached it, so no result will ever arrive. Recommended polling cadence: a few seconds for short jobs, tens of seconds for long-running jobs.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_job_status(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_result(...) -> typing.Any

Description

Get the measurement results of a completed quantum job as inline JSON. On success the payload is the provider-native result verbatim - the shape varies by backend. Use getNormalizedJobResult for a provider-independent view. Only valid once the job has reached a terminal result state (getJobStatus returns COMPLETED or FAILED); calling this on a job that has not yet completed returns 404. A FAILED job returns a common error envelope across all providers: {"error": {"message": "...", "code": "...", "details": {...}}} (code and details are optional; code is the provider's native error code passed through verbatim — the middleware defines no error codes of its own). Use getJobResultStream to download the same data as an attached JSON file (useful for large results).

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_job_result(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_normalized_job_result(...) -> typing.Optional[NormalizedJobResult]

Description

Get a provider-independent, normalized view of a completed quantum job's measurement results; the NormalizedJobResult schema describes the response shape. Only valid once the job has reached a terminal result state (getJobStatus returns COMPLETED or FAILED); calling this earlier returns 404. The view is defined only for gate-based measurement results: backends whose computing paradigm produces neither counts nor probabilities (e.g. photonic, neutral-atom) return 204, and so does a job in which no PUB carries a normalizable result.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_normalized_job_result(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_normalized_job_memory(...) -> typing.Optional[NormalizedMemoryResult]

Description

Get per-shot measurement values of a completed quantum job as Qiskit hex strings, under the same little-endian bit-order contract as getNormalizedJobResult's 'counts' type (clbit 0 is the rightmost character) - the same shot maps to the same bitstring across both endpoints. Returns 204 when no per-shot data exists: probability-native results (Azure IonQ), state-vector results, IQM (its API only ever exposes aggregated counts, never a genuine per-shot order), FAILED jobs, or providers with no normalized mapping. Only valid once the job has reached a terminal result state (getJobStatus returns COMPLETED or FAILED); calling this on a job that has not yet completed returns 404. The raw getJobResult endpoint is unaffected and stays byte-identical.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_normalized_job_memory(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_result_stream(...) -> typing.Iterator[bytes]

Description

Get the result of a specific job as json file. A FAILED job's downloaded file contains the same common error envelope as getJobResult: {"error": {"message": "...", "code": "...", "details": {...}}}.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_job_result_stream(
    id="id",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_input(...) -> typing.Dict[str, typing.Any]

Description

Get the input.json of a quantum job. Returns the provider-native input verbatim - the shape varies by backend. Use getNormalizedJobInput for a provider-independent QASM view.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_job_input(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_normalized_job_input(...) -> NormalizedJobInput

Description

Get the provider-independent QASM view of a quantum job's input. Returns 422 when the input cannot be rendered as QASM. The raw getJobInput endpoint is unaffected and stays byte-identical.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_normalized_job_input(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_calibration(...) -> typing.Optional[CalibrationResponse]

Description

Get the calibration for a specific job during its execution.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.jobs.get_job_calibration(
    id="5904a9f2-f43b-453d-9d08-beedcdb93e54",
)

Parameters

id: str — Unique job identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Workloads

client.workloads.get_workloads(...) -> PageResponseWorkloadResponse

Description

Get every quantum workload the caller's account is responsible for: workloads it created directly, plus workloads executed inside a service execution of one of the caller's own services (regardless of who triggered the execution). Pass origin=STANDALONE to get only the workloads the caller created directly. Filter params are ANDed across params and ORed within a repeated param.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.workloads.get_workloads(
    page=1,
    size=1,
    sort=[
        "sort"
    ],
    type=[
        "type"
    ],
    status=[
        "status"
    ],
    provider=[
        "provider"
    ],
    backend_id=[
        "backendId"
    ],
    tag=[
        "tag"
    ],
    origin=[
        "origin"
    ],
    service_execution_id=[
        "serviceExecutionId"
    ],
)

Parameters

page: typing.Optional[int] — Zero-based page index (0..N)

size: typing.Optional[int] — The size of the page to be returned

sort: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

type: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Filter by workload kind: JOB or SESSION (case-insensitive). Repeatable; matches any of the given values.

status: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Filter by workload status (case-insensitive), validated against the union of JobStatus and SessionStatus values. Repeatable; matches any of the given values.

provider: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Filter by quantum cloud provider (case-insensitive). Repeatable; matches any of the given values.

backend_id: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Filter by backend ID. Repeatable; matches any of the given values.

tag: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Filter by tag (case-insensitive). Repeatable; matches workloads carrying any of the given tags.

origin: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Filter by workload origin: STANDALONE (leaf context is the caller) or SERVICE_EXECUTION (workload was executed inside one of the caller's service executions). Repeatable; matches any of the given values.

service_execution_id: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Filter by the ID of the service execution the workload ran in. Repeatable; matches any of the given values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Runtime Minutes

client.runtime_minutes.get_runtime_minutes() -> RuntimeMinutesResponse

Description

List the calling tenant's prepaid runtime-minutes pools, read live from the provider.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.runtime_minutes.get_runtime_minutes()

Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Backends

client.backends.get_backends(...) -> typing.List[Backend]

Description

Get the list of backends based on the provided filters. This endpoint is publicly accessible; authenticated callers receive full operational details, unauthenticated callers receive a reduced view.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.backends.get_backends(
    provider="provider",
    only_planqk_sdk=True,
)

Parameters

provider: typing.Optional[str] — Filter backends by quantum hardware provider. Accepts one of: AZURE, AWS, IBM, QRYD, QUDORA, QUANDELA, IQM (case-insensitive; hyphens are normalized to underscores). Omit to return backends from all providers.

only_planqk_sdk: typing.Optional[bool] — When true, return only backends that are usable via the qhub-quantum SDK (excludes backends that require direct-only access). Defaults to false — all backends are returned.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.backends.get_backend(...) -> Backend

Description

Get the details of a specific backend.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.backends.get_backend(
    id="aws.sim.sv1",
)

Parameters

id: str — Unique backend identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.backends.get_backend_status(...) -> BackendStateInfo

Description

Get the status of a specific backend.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.backends.get_backend_status(
    id="aws.sim.sv1",
)

Parameters

id: str — Unique backend identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.backends.get_backend_config(...) -> typing.Dict[str, typing.Any]

Description

Get the configuration of a specific backend.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.backends.get_backend_config(
    id="aws.sim.sv1",
)

Parameters

id: str — Unique backend identifier

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.backends.get_backend_calibration(...) -> typing.Optional[CalibrationResponse]

Description

Get the calibration of a specific backend.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment
import datetime

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.backends.get_backend_calibration(
    id="aws.sim.sv1",
    effective_at=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
)

Parameters

id: str — Unique backend identifier

effective_at: typing.Optional[datetime.datetime] — Return the calibration that was effective at this instant instead of the latest one. Expected as an ISO-8601 timestamp in UTC (e.g. 2026-04-17T12:34:56Z). Omit to retrieve the most recent calibration. Returns 204 if no calibration exists at or before the given instant.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.backends.get_backend_calibration_history(...) -> PageResponseCalibrationResponse

Description

Get every calibration snapshot archived for a backend within a time interval, newest first by default. Each entry carries the instant the calibration became effective and the same normalized payload the singular calibration endpoint serves. An interval that holds no snapshot returns an empty page, as does any interval on a simulator, because simulators carry no calibration at all.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment
import datetime

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.backends.get_backend_calibration_history(
    id="aws.sim.sv1",
    from_=datetime.datetime.fromisoformat("2026-09-01T00:00:00+00:00"),
    to=datetime.datetime.fromisoformat("2026-09-08T00:00:00+00:00"),
    page=1,
    size=1,
    sort=[
        "sort"
    ],
)

Parameters

id: str — Unique backend identifier

from: datetime.datetime — Start of the interval, inclusive. Expected as an ISO-8601 timestamp in UTC (e.g. 2026-09-01T00:00:00Z). A timestamp without a zone is rejected. A numeric offset such as +02:00 must be percent-encoded, because a bare + means a space in a query string. Fractional seconds finer than a microsecond are rounded to the nearest microsecond by the store, so a bound can move by up to half a microsecond in either direction.

to: datetime.datetime — End of the interval, inclusive. Expected as an ISO-8601 timestamp in UTC (e.g. 2026-09-08T00:00:00Z), with the same zone, offset-encoding and microsecond rules as from. Because both bounds are inclusive, consecutive windows share the snapshot on their common boundary: deduplicate on calibratedAt when you walk a range.

page: typing.Optional[int] — Zero-based page index (0..N)

size: typing.Optional[int] — The size of the page to be returned

sort: typing.Optional[typing.Union[str, typing.Sequence[str]]] — Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.backends.get_least_busy_backend(...) -> Backend

Description

Returns the single backend with the lowest reported queue size for the requested provider. Currently only IBM is supported — other providers do not yet report per-backend queue depth and will return 400 ("Provider X does not support least-busy backend selection"). Returns 404 if no eligible operational IBM backends with known queue information are available.

Usage

from qhub.api.quantum import HubQuantumClient
from qhub.api.quantum.environment import HubQuantumClientEnvironment

client = HubQuantumClient(
    api_key="<value>",
    environment=HubQuantumClientEnvironment.DEFAULT,
)

client.backends.get_least_busy_backend(
    provider="provider",
    min_qubits=1,
)

Parameters

provider: str — Quantum provider. Matches the /backends provider parameter (case-insensitive, hyphens normalised to underscores). Only providers that report per-backend queue depth are eligible; currently this is IBM only — other values return 400.

min_qubits: typing.Optional[int] — Optional lower bound on the backend's qubit count. Backends with fewer qubits are excluded from selection.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

TypeScript reference

Sessions

client.sessions.createSession({ ...params }) -> HubQuantum.Session

Description

Create a new quantum session that groups related quantum jobs on a shared backend. Sessions reserve backend resources so subsequent jobs in the session run with reduced queue latency. Prefer a session when submitting multiple related jobs to the same backend; otherwise submit standalone jobs via createJob. The session remains open until explicitly closed (closeSession) or its ttl expires. Returns 422 if the selected backend does not support sessions.

Usage

await client.sessions.createSession({
    backend_id: "aws.sim.sv1",
    mode: "batch",
    provider: "AZURE"
});

Parameters

request: HubQuantum.CreateSessionRequest

requestOptions: SessionsClient.RequestOptions

client.sessions.getSession(id) -> HubQuantum.Session

Description

Get a quantum session's details.

Usage

await client.sessions.getSession("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique session identifier

requestOptions: SessionsClient.RequestOptions

client.sessions.closeSession(id) -> void

Description

Close a quantum session and release its reserved backend resources. Jobs already submitted to the session are left to complete; no new jobs can be submitted once the session is closed. Idempotent: closing an already-closed session has no effect. To stop accepting new jobs without aborting the session, call updateSessionState with accept_jobs=false instead (DRAINING).

Usage

await client.sessions.closeSession("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique session identifier

requestOptions: SessionsClient.RequestOptions

client.sessions.updateSessionState(id, { ...params }) -> HubQuantum.Session

Description

Update a quantum session's state to control job acceptance.

Usage

await client.sessions.updateSessionState("5904a9f2-f43b-453d-9d08-beedcdb93e54", {
    accept_jobs: false
});

Parameters

id: string — Unique session identifier

request: HubQuantum.SessionStateUpdateRequest

requestOptions: SessionsClient.RequestOptions

client.sessions.getSessionStatus(id) -> HubQuantum.SessionStatusResponse

Description

Get a quantum session's status.

Usage

await client.sessions.getSessionStatus("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique session identifier

requestOptions: SessionsClient.RequestOptions

client.sessions.getSessionJobs(id) -> HubQuantum.Job

Description

Get all quantum jobs belonging to a session.

Usage

await client.sessions.getSessionJobs("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique session identifier

requestOptions: SessionsClient.RequestOptions

Jobs

client.jobs.searchJobs({ ...params }) -> HubQuantum.PageResponseJob

Description

Get quantum jobs with pagination.

Usage

await client.jobs.searchJobs({
    page: 1,
    size: 1,
    sort: ["sort"],
    serviceExecutionId: "5904a9f2-f43b-453d-9d08-beedcdb93e54"
});

Parameters

request: HubQuantum.SearchJobsRequest

requestOptions: JobsClient.RequestOptions

client.jobs.createJob({ ...params }) -> HubQuantum.Job

Description

Submit a new quantum job for asynchronous execution on a quantum backend. A job can run standalone or, when sessionId is provided, within an open session to share a priority slot on the backend. Execution is asynchronous: the returned job starts non-terminal — poll getJobStatus until it reaches a terminal state (COMPLETED, FAILED, CANCELLED, ABORTED, DETACHED), then retrieve measurement results via getJobResult.

Usage

await client.jobs.createJob({
    backend_id: "aws.sim.sv1",
    shots: 1000,
    input: {
        backendId: "aqt.qpu.ibex",
        job_type: "quantum_circuit",
        payload: {
            circuits: [{
                    repetitions: 100,
                    number_of_qubits: 2,
                    quantum_circuit: [{
                            "operation": "RZ",
                            "qubit": 0,
                            "phi": 0.5
                        }, {
                            "operation": "R",
                            "qubit": 1,
                            "phi": 0.5,
                            "theta": 1
                        }, {
                            "operation": "RXX",
                            "qubits": [
                                0,
                                1
                            ],
                            "theta": 0.5
                        }, {
                            "operation": "MEASURE"
                        }]
                }]
        }
    }
});

Parameters

request: HubQuantum.CreateJobRequest

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionSession(serviceExecutionId, sessionId) -> HubQuantum.Session

Description

Get the details of a quantum session running within a service execution.

Usage

await client.jobs.getServiceExecutionSession("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

sessionId: string — Unique session identifier

requestOptions: JobsClient.RequestOptions

client.jobs.closeServiceExecutionSession(serviceExecutionId, sessionId) -> void

Description

Close a quantum session running within a service execution.

Usage

await client.jobs.closeServiceExecutionSession("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

sessionId: string — Unique session identifier

requestOptions: JobsClient.RequestOptions

client.jobs.updateServiceExecutionSessionState(serviceExecutionId, sessionId, { ...params }) -> HubQuantum.Session

Description

Update the state of a quantum session running within a service execution (accept or reject jobs).

Usage

await client.jobs.updateServiceExecutionSessionState("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54", {
    accept_jobs: false
});

Parameters

serviceExecutionId: string — Unique service execution identifier

sessionId: string — Unique session identifier

request: HubQuantum.SessionStateUpdateRequest

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionWorkloads(serviceExecutionId, { ...params }) -> HubQuantum.PageResponseWorkloadResponse

Description

Get quantum workloads (jobs and sessions) running within a specific service execution with pagination.

Usage

await client.jobs.getServiceExecutionWorkloads("5904a9f2-f43b-453d-9d08-beedcdb93e54", {
    page: 1,
    size: 1,
    sort: ["sort"]
});

Parameters

serviceExecutionId: string — Unique service execution identifier

request: HubQuantum.GetServiceExecutionWorkloadsRequest

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionSessionStatus(serviceExecutionId, sessionId) -> HubQuantum.SessionStatusResponse

Description

Get the status of a quantum session running within a service execution.

Usage

await client.jobs.getServiceExecutionSessionStatus("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

sessionId: string — Unique session identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionSessionJobs(serviceExecutionId, sessionId) -> HubQuantum.Job

Description

Get all jobs belonging to a quantum session running within a service execution.

Usage

await client.jobs.getServiceExecutionSessionJobs("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

sessionId: string — Unique session identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionJob(serviceExecutionId, jobId) -> HubQuantum.Job

Description

Get the details of a quantum job running within a service execution.

Usage

await client.jobs.getServiceExecutionJob("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.cancelServiceExecutionJob(serviceExecutionId, jobId) -> void

Description

Cancel the execution of a quantum job running within a service execution.

Usage

await client.jobs.cancelServiceExecutionJob("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionJobStatus(serviceExecutionId, jobId) -> HubQuantum.JobStatusResponse

Description

Get the status of a quantum job running within a service execution.

Usage

await client.jobs.getServiceExecutionJobStatus("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionNormalizedJobResult(serviceExecutionId, jobId) -> HubQuantum.NormalizedJobResult | undefined

Description

Get a provider-independent, normalized view of the measurement results of a quantum job running within a service execution. The response is a discriminated union by 'type': 'counts' for real measurement tallies from sampled backends, 'probabilities' for state-vector-derived distributions, 'error' for a FAILED job (the common error envelope). All bitstring keys use Qiskit little-endian order (clbit 0 is the rightmost character). The normalized view is defined only for gate-based measurement results; backends whose computing paradigm does not produce gate-based counts or probabilities (e.g. photonic, neutral-atom) return 204, as do result shapes with no normalized mapping. Only valid once the job has reached a terminal result state (getServiceExecutionJobStatus returns COMPLETED or FAILED); calling this on a job that has not yet completed returns 404. The raw getServiceExecutionJobResultStream endpoint is unaffected and stays byte-identical.

Usage

await client.jobs.getServiceExecutionNormalizedJobResult("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionJobResultStream(serviceExecutionId, jobId) -> core.BinaryResponse

Description

Get the result of a quantum job running within a service execution as a JSON file. On success the file holds the provider-native result verbatim - the shape varies by backend. Use getServiceExecutionNormalizedJobResult for a provider-independent view.

Usage

await client.jobs.getServiceExecutionJobResultStream("serviceExecutionId", "jobId");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionJobInput(serviceExecutionId, jobId) -> Record<string, any>

Description

Get the input.json of a quantum job running within a service execution. Returns the provider-native input verbatim - the shape varies by backend. Use getServiceExecutionNormalizedJobInput for a provider-independent QASM view.

Usage

await client.jobs.getServiceExecutionJobInput("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionNormalizedJobInput(serviceExecutionId, jobId) -> HubQuantum.NormalizedJobInput

Description

Get the provider-independent QASM view of a quantum job's input, for a job running within a service execution. Returns 422 when the input cannot be rendered as QASM. The raw getServiceExecutionJobInput endpoint is unaffected and stays byte-identical.

Usage

await client.jobs.getServiceExecutionNormalizedJobInput("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getServiceExecutionJobCalibration(serviceExecutionId, jobId) -> HubQuantum.CalibrationResponse | undefined

Description

Get the calibration for a quantum job running within a service execution.

Usage

await client.jobs.getServiceExecutionJobCalibration("5904a9f2-f43b-453d-9d08-beedcdb93e54", "5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

serviceExecutionId: string — Unique service execution identifier

jobId: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getJob(id) -> HubQuantum.Job

Description

Get the full details of a quantum job, including status, timestamps, backend, and session affiliation. Fields populated depend on the job's lifecycle stage (e.g. execution timestamps appear once the job starts running). Use getJobStatus when only the status is needed (lighter and cheaper to poll), and getJobResult once the job reaches a terminal state to retrieve measurement results.

Usage

await client.jobs.getJob("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.cancelJob(id) -> void

Description

Cancel the execution of a quantum job.

Usage

await client.jobs.cancelJob("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getJobStatus(id) -> HubQuantum.JobStatusResponse

Description

Get just the current lifecycle status of a quantum job. Cheaper than getJob when polling. Non-terminal statuses (PENDING, RUNNING, CANCELLING) indicate the job is still being processed; terminal statuses (COMPLETED, FAILED, CANCELLED, ABORTED) indicate the job has finished and getJobResult can be called; DETACHED is terminal too, but means the job outlived the credential that reached it, so no result will ever arrive. Recommended polling cadence: a few seconds for short jobs, tens of seconds for long-running jobs.

Usage

await client.jobs.getJobStatus("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getJobResult(id) -> any

Description

Get the measurement results of a completed quantum job as inline JSON. On success the payload is the provider-native result verbatim - the shape varies by backend. Use getNormalizedJobResult for a provider-independent view. Only valid once the job has reached a terminal result state (getJobStatus returns COMPLETED or FAILED); calling this on a job that has not yet completed returns 404. A FAILED job returns a common error envelope across all providers: {"error": {"message": "...", "code": "...", "details": {...}}} (code and details are optional; code is the provider's native error code passed through verbatim — the middleware defines no error codes of its own). Use getJobResultStream to download the same data as an attached JSON file (useful for large results).

Usage

await client.jobs.getJobResult("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getNormalizedJobResult(id) -> HubQuantum.NormalizedJobResult | undefined

Description

Get a provider-independent, normalized view of a completed quantum job's measurement results; the NormalizedJobResult schema describes the response shape. Only valid once the job has reached a terminal result state (getJobStatus returns COMPLETED or FAILED); calling this earlier returns 404. The view is defined only for gate-based measurement results: backends whose computing paradigm produces neither counts nor probabilities (e.g. photonic, neutral-atom) return 204, and so does a job in which no PUB carries a normalizable result.

Usage

await client.jobs.getNormalizedJobResult("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getNormalizedJobMemory(id) -> HubQuantum.NormalizedMemoryResult | undefined

Description

Get per-shot measurement values of a completed quantum job as Qiskit hex strings, under the same little-endian bit-order contract as getNormalizedJobResult's 'counts' type (clbit 0 is the rightmost character) - the same shot maps to the same bitstring across both endpoints. Returns 204 when no per-shot data exists: probability-native results (Azure IonQ), state-vector results, IQM (its API only ever exposes aggregated counts, never a genuine per-shot order), FAILED jobs, or providers with no normalized mapping. Only valid once the job has reached a terminal result state (getJobStatus returns COMPLETED or FAILED); calling this on a job that has not yet completed returns 404. The raw getJobResult endpoint is unaffected and stays byte-identical.

Usage

await client.jobs.getNormalizedJobMemory("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getJobResultStream(id) -> core.BinaryResponse

Description

Get the result of a specific job as json file. A FAILED job's downloaded file contains the same common error envelope as getJobResult: {"error": {"message": "...", "code": "...", "details": {...}}}.

Usage

await client.jobs.getJobResultStream("id");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getJobInput(id) -> Record<string, any>

Description

Get the input.json of a quantum job. Returns the provider-native input verbatim - the shape varies by backend. Use getNormalizedJobInput for a provider-independent QASM view.

Usage

await client.jobs.getJobInput("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getNormalizedJobInput(id) -> HubQuantum.NormalizedJobInput

Description

Get the provider-independent QASM view of a quantum job's input. Returns 422 when the input cannot be rendered as QASM. The raw getJobInput endpoint is unaffected and stays byte-identical.

Usage

await client.jobs.getNormalizedJobInput("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

client.jobs.getJobCalibration(id) -> HubQuantum.CalibrationResponse | undefined

Description

Get the calibration for a specific job during its execution.

Usage

await client.jobs.getJobCalibration("5904a9f2-f43b-453d-9d08-beedcdb93e54");

Parameters

id: string — Unique job identifier

requestOptions: JobsClient.RequestOptions

Workloads

client.workloads.getWorkloads({ ...params }) -> HubQuantum.PageResponseWorkloadResponse

Description

Get every quantum workload the caller's account is responsible for: workloads it created directly, plus workloads executed inside a service execution of one of the caller's own services (regardless of who triggered the execution). Pass origin=STANDALONE to get only the workloads the caller created directly. Filter params are ANDed across params and ORed within a repeated param.

Usage

await client.workloads.getWorkloads({
    page: 1,
    size: 1,
    sort: ["sort"],
    type: ["type"],
    status: ["status"],
    provider: ["provider"],
    backendId: ["backendId"],
    tag: ["tag"],
    origin: ["origin"],
    serviceExecutionId: ["serviceExecutionId"]
});

Parameters

request: HubQuantum.GetWorkloadsRequest

requestOptions: WorkloadsClient.RequestOptions

Runtime Minutes

client.runtimeMinutes.getRuntimeMinutes() -> HubQuantum.RuntimeMinutesResponse

Description

List the calling tenant's prepaid runtime-minutes pools, read live from the provider.

Usage

await client.runtimeMinutes.getRuntimeMinutes();

Parameters

requestOptions: RuntimeMinutesClient.RequestOptions

Backends

client.backends.getBackends({ ...params }) -> HubQuantum.Backend[]

Description

Get the list of backends based on the provided filters. This endpoint is publicly accessible; authenticated callers receive full operational details, unauthenticated callers receive a reduced view.

Usage

await client.backends.getBackends({
    provider: "provider",
    onlyPlanqkSdk: true
});

Parameters

request: HubQuantum.GetBackendsRequest

requestOptions: BackendsClient.RequestOptions

client.backends.getBackend(id) -> HubQuantum.Backend

Description

Get the details of a specific backend.

Usage

await client.backends.getBackend("aws.sim.sv1");

Parameters

id: string — Unique backend identifier

requestOptions: BackendsClient.RequestOptions

client.backends.getBackendStatus(id) -> HubQuantum.BackendStateInfo

Description

Get the status of a specific backend.

Usage

await client.backends.getBackendStatus("aws.sim.sv1");

Parameters

id: string — Unique backend identifier

requestOptions: BackendsClient.RequestOptions

client.backends.getBackendConfig(id) -> Record<string, any>

Description

Get the configuration of a specific backend.

Usage

await client.backends.getBackendConfig("aws.sim.sv1");

Parameters

id: string — Unique backend identifier

requestOptions: BackendsClient.RequestOptions

client.backends.getBackendCalibration(id, { ...params }) -> HubQuantum.CalibrationResponse | undefined

Description

Get the calibration of a specific backend.

Usage

await client.backends.getBackendCalibration("aws.sim.sv1", {
    effectiveAt: "2024-01-15T09:30:00Z"
});

Parameters

id: string — Unique backend identifier

request: HubQuantum.GetBackendCalibrationRequest

requestOptions: BackendsClient.RequestOptions

client.backends.getBackendCalibrationHistory(id, { ...params }) -> HubQuantum.PageResponseCalibrationResponse

Description

Get every calibration snapshot archived for a backend within a time interval, newest first by default. Each entry carries the instant the calibration became effective and the same normalized payload the singular calibration endpoint serves. An interval that holds no snapshot returns an empty page, as does any interval on a simulator, because simulators carry no calibration at all.

Usage

await client.backends.getBackendCalibrationHistory("aws.sim.sv1", {
    from: "2026-09-01T00:00:00Z",
    to: "2026-09-08T00:00:00Z",
    page: 1,
    size: 1,
    sort: ["sort"]
});

Parameters

id: string — Unique backend identifier

request: HubQuantum.GetBackendCalibrationHistoryRequest

requestOptions: BackendsClient.RequestOptions

client.backends.getLeastBusyBackend({ ...params }) -> HubQuantum.Backend

Description

Returns the single backend with the lowest reported queue size for the requested provider. Currently only IBM is supported — other providers do not yet report per-backend queue depth and will return 400 ("Provider X does not support least-busy backend selection"). Returns 404 if no eligible operational IBM backends with known queue information are available.

Usage

await client.backends.getLeastBusyBackend({
    provider: "provider",
    minQubits: 1
});

Parameters

request: HubQuantum.GetLeastBusyBackendRequest

requestOptions: BackendsClient.RequestOptions