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.

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

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

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

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

{
  "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
`rate_limited`	The caller is over the rate limit for its key kind.	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
`unauthorized`	The `Authorization` header is missing, malformed or names an unknown key.	unauthorized

Every error body carries the same shape; the full list is on Errors.