API Client¶

Basic API Client for IonQ’s REST API

class qiskit_ionq.ionq_client.Characterization(data: dict)[source]¶

Simple wrapper around the /backends/<backend>/characterizations/<uuid> payload.

property backend: str¶: Backend name, e.g. “qpu.aria-1”.

property connectivity: list[tuple[int, int]]¶: Valid two-qubit gate pairs as a list of tuples.

property date: datetime¶: Timestamp of the measurement (UTC).

property fidelity: dict¶: Full fidelity dictionary (spam, 1q, 2q, …).

property id: str¶: UUID of this characterization.

property median_spam_fidelity: float | None¶: Median state-prep-and-measurement fidelity, if present.

property qubits: int¶: Number of qubits available.

property status: str¶: Status of the characterization, e.g. “available”.

property timing: dict¶: Dictionary of timing parameters (readout, reset, 1q, 2q, t1, t2).

class qiskit_ionq.ionq_client.IonQClient(token: str | None = None, url: str | None = None, custom_headers: dict | None = None)[source]¶

IonQ API Client

_url¶

A URL base to use for API calls, e.g. "https://api.ionq.co/v0.4"

Type:: str

_token¶

An API Access Token to use with the IonQ API.

Type:: str

_custom_headers¶

Extra headers to add to the request.

Type:: dict

property api_headers: dict¶

API Headers needed to make calls to the REST API.

Returns:: A dict of requests.Request headers.
Return type:: dict[str, str]

cancel_job(job_id: str) → dict[source]¶

Attempt to cancel a job which has not yet run.

Note

If the job has already reached status “completed”, this cancel action is a no-op.

Parameters:: job_id (str) – The ID of the job to cancel.
Raises:: IonQAPIError – When the API returns a non-200 status code.
Returns:: A requests response json dict.
Return type:: dict

cancel_jobs(job_ids: list[str]) → list[dict][source]¶

Cancel multiple jobs at once.

Parameters:: job_ids (list) – A list of job IDs to cancel.
Returns:: A list of cancel_job responses.
Return type:: list

delete_job(job_id: str) → dict[source]¶

Delete a job and associated data.

Parameters:: job_id (str) – The ID of the job to delete.
Raises:: IonQAPIError – When the API returns a non-200 status code.
Returns:: A requests response json dict.
Return type:: dict

estimate_job(*, backend: str, oneq_gates: int, twoq_gates: int, qubits: int, shots: int, error_mitigation: bool = False, session: bool = False, job_type: str = 'ionq.circuit.v1') → JobEstimate[source]¶: Call GET /jobs/estimate … returns a cost/time prediction.

get_calibration_data(backend_name: str, limit: int | None = None) → Characterization | list[Characterization][source]¶

Retrieve calibration data for a specified backend.

Parameters:

backend_name (str) – The IonQ backend to fetch data for.
limit (int, optional) – Limit the number of results returned.

Raises:

IonQAPIError – When the API returns a non-200 status code.
IonQRetriableError – When a retriable error occurs during the request.

Returns:

An instance of Characterization containing the calibration data or a list of Characterization instances if multiple results are returned.

Return type:

Characterization

get_results(results_url: str, sharpen: bool | None = None, extra_query_params: dict | None = None) → dict[source]¶

Retrieve job results from the IonQ API.

The returned JSON dict will only have data if job has completed.

Parameters:

results_url (str) – The URL of the job results to retrieve.
sharpen (bool) – Supported if the job is debiased,
results. (allows you to filter out physical qubit bias from the)
extra_query_params (dict) – Specify any parameters to include in the request

Raises:

IonQAPIError – When the API returns a non-200 status code.
IonQRetriableError – When a retriable error occurs during the request.

Returns:

A requests response json dict.

Return type:

dict

get_with_retry(req_path, params=None, headers=None, timeout=30)[source]¶

Make a GET request with retry logic and exception handling.

Parameters:

req_path (str) – The URL path to make the request to.
params (dict, optional) – Parameters to include in the request.
headers (dict, optional) – Headers to include in the request.
timeout (int, optional) – Timeout for the request.

Raises:

IonQRetriableError – When a retriable error occurs during the request.

Returns:

A requests.Response object.

Return type:

Response

make_path(*parts: str) → str[source]¶

Make a “/”-delimited path, then append it to _url.

Returns:: A URL to use for an API call.
Return type:: str

post(*path_parts: str, json_body: dict | None = None) → dict[source]¶

POST helper with IonQ headers + retry.

Parameters:

*path_parts (str) – Path parts to append to the base URL.
json_body (dict, optional) – JSON body to send in the POST request.

Raises:

IonQAPIError – When the API returns a non-200 status code.
IonQRetriableError – When a retriable error occurs during the request.

Returns:

A requests response json dict.

Return type:

dict

put(*path_parts: str, json_body: dict | None = None) → dict[source]¶

PUT helper with IonQ headers + retry.

Parameters:

*path_parts (str) – Path parts to append to the base URL.
json_body (dict, optional) – JSON body to send in the PUT request.

Raises:

IonQAPIError – When the API returns a non-200 status code.
IonQRetriableError – When a retriable error occurs during the request.

Returns:

A requests response json dict.

Return type:

dict

retrieve_job(job_id: str) → dict[source]¶

Retrieve job information from the IonQ API.

The returned JSON dict will only have data if job has completed.

Parameters:

job_id (str) – The ID of a job to retrieve.

Raises:

IonQAPIError – When the API returns a non-200 status code.
IonQRetriableError – When a retriable error occurs during the request.

Returns:

A requests response json dict.

Return type:

dict

submit_job(job: IonQJob) → dict[source]¶

Submit job to IonQ API

This returns a JSON dict with status “submitted” and the job’s id.

Parameters:: job (IonQJob) – The IonQ Job instance to submit to the API.
Raises:: IonQAPIError – When the API returns a non-200 status code.
Returns:: A requests response json dict.
Return type:: dict

class qiskit_ionq.ionq_client.JobEstimate(data: dict)[source]¶

Wrapper for the payload returned by GET /jobs/estimate.

to_dict() → dict[source]¶: Return a shallow copy of the original JSON dict.

property total_runtime: float | None¶: Predicted queue + execution time, in seconds (if both are present).