API Client¶

Basic API Client for IonQ’s REST API

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.3"

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

get_calibration_data(backend_name: str) → dict[source]¶

Retrieve calibration data for a specified backend.

Parameters:

backend_name (str) – The IonQ backend to fetch data for.

Raises:

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

Returns:

A dictionary of an IonQ backend’s calibration data.

Return type:

dict

get_results(job_id: 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:

job_id (str) – The ID of a job 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

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

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