scans¶

List recent scans

The account's scans, most recent first, as history rows, one page at a time. 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. limit sets the page size (1 to 100, default 100) and cursor continues from the next_cursor of the previous page, which is null on the last one. 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.

The list comes a page at a time. limit sets the page size, 1 to 100, and defaults to 100. Send the next_cursor of one page back as cursor to read the next; it is null on the last page.

Request¶


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

Responses¶

200¶

One page of the account's recent scans.

Body: ScanList.

Field	Type	Description
`scans`	ScanSummary[]	The account's scans, most recent first.
`next_cursor`	object	Opaque cursor for the next page: send it back as `cursor` to continue after the last row of this one. Null on the last page.

{
  "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"
    }
  ],
  "next_cursor": null
}

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

403¶

The credential cannot call this operation: a client token can only call POST /v1/scans.

Body: ErrorResponse.

{
  "error": {
    "code": "client_token_not_allowed",
    "message": "A client token can only call POST /v1/scans.",
    "docs_url": "https://doc.cheap/docs/errors/client_token_not_allowed",
    "request_id": "req_9e6b1f7c-2d4a-4b83-9c51-7f0ad3e8b642",
    "event_id": null
  }
}

422¶

The body is well-formed JSON but does not satisfy the request schema.

Body: ErrorResponse.

{
  "error": {
    "code": "validation_failed",
    "message": "/options/mode: Invalid option: expected one of \"full\"",
    "docs_url": "https://doc.cheap/docs/errors/validation_failed",
    "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
`client_token_not_allowed`	A client token was presented. A client token can only call `POST /v1/scans`; read this with the API key.	client_token_not_allowed
`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
`validation_failed`	`limit` is not a whole number from 1 to 100, or `cursor` is not a cursor this API issued.	validation_failed

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