API Core Concepts

​

Jobs

A job is the basic unit of work on the IonQ cloud. Whether you’re simulating a simple circuit, or submitting a program to run on our world-class hardware, you’ll send it along as a job.

​

Quantum Programs

Quantum programs are collections of circuits to be run on a QPU. They are submitted to a job in the input parameter. Examples can be found on the Writing Quantum Programs

​

Metadata

Updatable resources (such as a Job) can store arbitrary metadata for your convenience — we store but ignore it. For example, you could tag different algorithms or projects for later analysis, or if you’re building an app, tag jobs submitted by customers with a unique customer ID.

{
    "metadata": {
        "custom_key": "a string, maximum 400 chars"
    },
    "input": { ... }
}

​

Authorization

API keys are associated with a user and can be created on the IonQ Quantum Cloud application. To authenticate, prefix your API Key with apiKey and place it in the Authorization request header. For example:

Authorization: apiKey {your-api-key}

​

Pagination

You can bulk fetch any resource (for example, list all jobs you have access to).

In addition to any specific query parameters those endpoints may support for filtering, all endpoints returning multiple resources take two parameters for pagination: next and limit. limit tells us how many objects to return; next identifies the next chunk of the iteration.

When loading a paginated resource, you’ll receive a next key with each page. Pass it to subsequent queries with a next querystring to fetch the next batch.

curl -H "Authorization: apiKey ..." "https://api.ionq.co/v0.3/jobs?limit=100&next=dce01d5c-987e-48e8-b2b7-41c24d69d711"

{
"jobs": [ ... ],
"next": "38f525e4-f865-48f6-a996-dab85ba1f7b0"
}

​

HTTP Responses

IonQ uses standard HTTP response status codes to indicate the result of a request.

​

Success

A successful response will have a status code in the 2XX range. Successful responses are documented above on a per-endpoint basis.

​

Bad Request

A request that contained invalid input data will have a 400 response status code and response data indicating the invalid items:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "\"some-parameter\" was invalid.",
    "validation": {
        "keys": [
        "some-parameter"
        ],
        "source": "params"
    }
}

​

Unauthorized

A request that fails API Authentication will receive a 401. See API Key for more details.

{
    "statusCode": 401,
    "error": "Unauthorized Error",
    "message": "Invalid key provided. See https://docs.ionq.com/#authentication for details, or email [email protected] for help."
}

​

Not Found

A request whose resource does not exist will have a 404 response status code and some detail about the missing resource:

{
    "statusCode": 404,
    "error": "Not Found Error",
    "message": "Resource not found. See https://docs.ionq.com/ for details, or email [email protected] for help."
}

​

Internal Server Error

Any unexpected errors are indicated by the 500 response status code.

Internal service outage. Visit https://status.ionq.co/ to track this incident.

{
    "statusCode": 500,
    "error": "Internal Server Error",
    "message": "Internal service outage. Visit https://status.ionq.co/ to track this incident."
}