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