> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Core Concepts

<Note>
  This page details some concepts specific to how the API works. There is also a more-general [platform glossary](/user-manual/glossary) as well as a [quantum-focused glossary on ionq.com](https://ionq.com/resources/glossary).
</Note>

## 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](/api-reference/v0.3/writing-quantum-programs) page.

***

## Metadata

Updatable resources (such as a [Job](/api-reference/v0.3/jobs)) 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.

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

```json theme={null}
{
    "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](https://cloud.ionq.com) application. To authenticate, prefix your API Key with `apiKey ` and place it in the `Authorization` request header. For example:

```
Authorization: apiKey {your-api-key}
```

<Tip>
  If you're new to managing API keys, [learn more in our guide](/guides/managing-api-keys).
</Tip>

***

## Pagination

You can bulk fetch any resource (for example, [list all jobs](/api-reference/v0.3/jobs/get-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.

```bash theme={null}
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:

```json theme={null}
{
    "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](#authorization) for more details.

```json theme={null}
{
    "statusCode": 401,
    "error": "Unauthorized Error",
    "message": "Invalid key provided. See https://docs.ionq.com/#authentication for details, or email support@ionq.co 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:

```json theme={null}
{
    "statusCode": 404,
    "error": "Not Found Error",
    "message": "Resource not found. See https://docs.ionq.com/ for details, or email support@ionq.co for help."
}
```

### Internal Server Error

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

Internal service outage. Visit [https://status.ionq.co/](https://status.ionq.co/) to track this incident.

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