# Read usage records

> Returns the usage records of the API key that makes the call, page by page, in the order they were written. Today the answer has one block, `sandboxes`: the usage records of the [Sandboxes](https://docs.serenityedge.ai/docs/sandboxes/overview/) created with this key, the records your sandbox invoice is computed from. Inference has no usage records to read: the `usage` object of each response is what is billed.

Source: https://docs.serenityedge.ai/docs/api/edge/get-usage/

`GET https://api.serenityedge.ai/v1/usage`

Returns the usage records of the API key that makes the call, page by page, in the order they were written. Today the answer has one block, `sandboxes`: the usage records of the [Sandboxes](https://docs.serenityedge.ai/docs/sandboxes/overview/) created with this key, the records your sandbox invoice is computed from. Inference has no usage records to read: the `usage` object of each response is what is billed.

**Whose records.** The calling key's only. Each key of an account reads the records of the sandboxes it created, and no other key's. Send the key as `Authorization: Bearer <key>` or as `X-API-Key: <key>`. A key whose account does not have Sandboxes gets `403 permission_denied`; a key of an account with Sandboxes that has not created a sandbox yet gets an empty page.

**Paging.** Start without `cursor`, then send the `next_cursor` of each page as `cursor` until `has_more` is `false`. The cursor is opaque and belongs to the key that read the page. Keep the last `next_cursor` to read only the records written since.

**Freshness.** A running sandbox's record is written every 5 minutes and when the run ends, a paused sandbox's every hour and when the pause ends. `watermark` is the time up to which every sandbox event has been recorded.

**Limits.** Each key may have 2 usage requests in flight and make 30 per minute. They are apart from the key's [control API limits](https://docs.serenityedge.ai/docs/sandboxes/limits-and-quotas/#request-limits): reading usage never uses the budget of your sandbox calls, nor they its budget. Over them, the answer is `429 rate_limit_exceeded` with `Retry-After`.

Errors are in the [OpenAI error format](https://docs.serenityedge.ai/docs/errors-and-rate-limits). See [Check your usage](https://docs.serenityedge.ai/docs/sandboxes/pricing-and-usage/#check-your-usage).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no | The `next_cursor` of the previous page, read with the same key. Omit it to read from the key's first record. |
| `limit` | query | integer | no | The most records in the page. Default `100`. At least 1. At most 1000. |

## Responses

### 200: A page of the key's usage records.

Body (`application/json`): `UsageResponse`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | Always `usage`. |
| `sandboxes` | SandboxUsagePage (object) | yes | A page of the calling key's sandbox usage records. |
| `sandboxes.records` | array of SandboxUsageRecord (object) | yes | The records, in the order they were written. |
| `sandboxes.records[].id` | string | yes | The record's unique id, 64 hexadecimal characters. Count each id once. |
| `sandboxes.records[].sandbox_id` | string | yes | The sandbox the interval belongs to. |
| `sandboxes.records[].written_at` | string | yes | When the record was written, in UTC with milliseconds. An adjustment counts in the month it is written. |
| `sandboxes.records[].metadata` | object | yes | The sandbox's metadata, as set at create, with the keys Serenity Edge adds: `edge.partner_key` is a short fingerprint of the key that created the sandbox, never the key itself. |
| `sandboxes.records[].interval` | SandboxUsageInterval (object) | yes | The billed span of a record. |
| `sandboxes.records[].interval.start` | UsageTimestamp (string) | yes | A time in UTC with milliseconds, such as `2026-11-17T16:20:00.000Z`. |
| `sandboxes.records[].interval.end` | UsageTimestamp (string) | yes | A time in UTC with milliseconds, such as `2026-11-17T16:20:00.000Z`. |
| `sandboxes.records[].interval.kind` | string | yes | `run` for a running sandbox, `paused` for a paused one, `adjustment` for a correction of an earlier record. One of `run`, `paused`, `adjustment`. |
| `sandboxes.records[].interval.end_reason` | string | yes | Why the interval ended; see [How usage is recorded](https://docs.serenityedge.ai/docs/sandboxes/pricing-and-usage/#how-usage-is-recorded). One of `interval`, `client_close`, `ttl`, `pause`, `resume`, `platform_failure`, `quota`. |
| `sandboxes.records[].adjusts` | string | no | Only on an `adjustment`: the `id` of the record it corrects. |
| `sandboxes.records[].shape` | SandboxUsageShape (object) | yes | The reserved size of the sandbox. |
| `sandboxes.records[].shape.vcpu` | integer | yes | Reserved vCPUs. |
| `sandboxes.records[].shape.memory_mib` | integer | yes | Reserved memory in MiB. |
| `sandboxes.records[].shape.disk_mib` | integer | yes | Disk size in MiB. |
| `sandboxes.records[].vcpu_seconds_reserved` | string | yes | Reserved vCPU-seconds of the interval, an exact decimal string (negative only on an adjustment). |
| `sandboxes.records[].memory_gib_seconds_reserved` | string | yes | Reserved memory in GiB-seconds, an exact decimal string. |
| `sandboxes.records[].paused_gib_hours` | string | yes | Stored GiB-hours while paused, an exact decimal string. |
| `sandboxes.records[].rate_card` | string | yes | The id of the price list used, such as `2026-11-v1`. |
| `sandboxes.records[].amount_nano_usd` | integer | yes | The amount of the interval in billionths of a US dollar (11100000 is 0.0111 USD). Signed on an adjustment. |
| `sandboxes.records[].currency` | string | yes | The currency of `amount_nano_usd`. Always `USD`. |
| `sandboxes.next_cursor` | string or null | yes | Send it as `cursor`, with the same key, to read the records written after this page. Opaque. `null` while the key has no record; after an empty page read with a `cursor`, the same cursor. |
| `sandboxes.has_more` | boolean | yes | Whether more records were already there when the page was read. |
| `sandboxes.watermark` | string or null | yes | Every sandbox event up to this time (UTC, milliseconds) is in the records. `null` until the first events have been recorded. |

### 400: A query parameter other than `cursor` and `limit`, one of them given twice, a `limit` outside 1 to 1000, or a `cursor` that is not a `next_cursor` of a page read with this key (`invalid_request_error`, with `param`).

Body (`application/json`): `ErrorResponse`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | Error (object) | yes | OpenAI-style error object. |
| `error.message` | string | yes | Human-readable description of the problem. |
| `error.type` | string | yes | Error category. One of `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`. |
| `error.code` | string or null | no | Machine-readable error code, when available. |
| `error.param` | string or null | no | The request parameter the error refers to, when applicable. |

### 401: Missing, malformed or revoked API key (`invalid_api_key`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 403: The key's account does not have Sandboxes, so the key has no usage records to read (`permission_denied`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 404: A method other than `GET` (`not_found`).

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 429: Over the key's usage limits, or too many pages being read at once (`rate_limit_exceeded`). Wait for `Retry-After`.

Header `Retry-After`: Seconds to wait before retrying.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.

### 503: The usage records cannot be read for a moment (`upstream_unavailable`). Retry after `Retry-After`.

Header `Retry-After`: Seconds to wait before retrying.

Body (`application/json`): `ErrorResponse`, the same fields as under 400.
