This page details some concepts specific to how the API works. There is also a more-general platform glossary as well as a quantum-focused glossary on ionq.com.

​
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 page.

​
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.

You can specify up to 10 keys, with names up to 40 characters long and values up to 40000 characters long.

{
    "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}

If you’re new to managing API keys, learn more in our guide.

​
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 Authorization 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."
}