# GET /v1/scans

List recent scans

The account's scans, most recent first, as history rows. Only scans made with a live key and kept under a non-zero retention window are listed, and only while that window lasts; a sandbox key sees an empty list. The full result of any one scan is read back through `GET /v1/scans/{id}`.

Lists the account's stored scans, most recent first, as history rows. The full result of one scan is read with `GET /v1/scans/{id}`.

Only scans made with a live key and kept under a non-zero retention window are listed, and only while that window lasts. A sandbox key sees an empty list.

## Request

| | |
|---|---|
| Method | `GET` |
| Path | `/v1/scans` |
| Authentication | `Authorization: Bearer <api key>` |

## Responses

### 200

The account's recent scans.

Body: `ScanList`.

| Field | Type | Description |
|---|---|---|
| `scans` | ScanSummary[] | The account's scans, most recent first. |

```json
{
  "scans": [
    {
      "id": "01a0af18-cd8d-7a61-9f2d-4c7b8e105da3",
      "status": "recognized",
      "billed": true,
      "duration_ms": 843,
      "reference": "order-1042",
      "created_at": "2026-09-17T09:41:12Z"
    },
    {
      "id": "01a0af19-8595-7f03-8a15-27e6b9c40f82",
      "status": "no_document_found",
      "billed": false,
      "duration_ms": 512,
      "reference": null,
      "created_at": "2026-09-17T09:18:44Z"
    }
  ]
}
```

### 401

Missing or malformed `Authorization: Bearer <api key>` header, or an unknown key.

Body: `ErrorResponse`.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Send your API key as `Authorization: Bearer <key>`.",
    "docs_url": "https://doc.cheap/docs/errors/unauthorized",
    "request_id": "req_9e6b1f7c-2d4a-4b83-9c51-7f0ad3e8b642",
    "event_id": null
  }
}
```

### 429

Rate limit exceeded for this key or IP.

Body: `ErrorResponse`.

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Sandbox limit of 10 requests per hour per IP reached.",
    "docs_url": "https://doc.cheap/docs/errors/rate_limited",
    "request_id": "req_9e6b1f7c-2d4a-4b83-9c51-7f0ad3e8b642",
    "event_id": null
  }
}
```

### 500

Unexpected failure on the server; the scan was not charged.

Body: `ErrorResponse`.

```json
{
  "error": {
    "code": "internal_error",
    "message": "Unexpected error.",
    "docs_url": "https://doc.cheap/docs/errors/internal_error",
    "request_id": "req_9e6b1f7c-2d4a-4b83-9c51-7f0ad3e8b642",
    "event_id": null
  }
}
```

### 503

Temporarily unable to serve the request: a store this service depends on is unreachable. Nothing was charged and it may be retried, after the `Retry-After` seconds where that header is present.

Body: `ErrorResponse`.

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "The service is temporarily unable to handle this request; nothing was charged. Retry shortly.",
    "docs_url": "https://doc.cheap/docs/errors/service_unavailable",
    "request_id": "req_9e6b1f7c-2d4a-4b83-9c51-7f0ad3e8b642",
    "event_id": null
  }
}
```

## Error codes reachable here

| Code | When | Page |
|---|---|---|
| `internal_error` | The service failed in a way it does not model. | [internal_error](https://doc.cheap/docs/errors/internal_error) |
| `rate_limited` | The caller is over the rate limit for its key kind. | [rate_limited](https://doc.cheap/docs/errors/rate_limited) |
| `service_unavailable` | A store this endpoint reads from is unreachable, so the answer could not be produced. Nothing was charged; retry after the `Retry-After` seconds. | [service_unavailable](https://doc.cheap/docs/errors/service_unavailable) |
| `unauthorized` | The `Authorization` header is missing, malformed or names an unknown key. | [unauthorized](https://doc.cheap/docs/errors/unauthorized) |

Every error body carries the same shape; the full list is on [Errors](https://doc.cheap/docs/reference/errors).