usage¶

Balance and usage for the current period

The credits available to the key's account and the scans made in the current usage period, counted by status. The balance has two parts: the free credits, 100 every month, set back to 100 at 00:00 UTC on the first and drawn first, and the paid credits, which never reset. Every settled scan is counted, whether or not its result was stored, so the figures do not decay as retention windows pass. A key with no account behind it (the public sandbox key) reports a null balance and zero counters.

Reports the balance in credits and the counters for the current period. One credit is one US cent, and one recognized document draws one, so the balance is also the number of documents left.

A sandbox key reads its own account's real figures. Its own scans are never charged, so they move the counters and not the balance.

Request¶


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

Responses¶

200¶

Balance and counters.

Body: Usage.

Field	Type	Description
`balance_credits`	integer \| null	Credits currently available to the account: this month's free credits plus the paid credits; null for a key with no account (the public sandbox key).
`period`	object	Bounds of the current usage period (UTC calendar month).
`scans`	object
`credits_spent`	integer	Credits charged within the period.
`free_allowance`	object \| null	This month's free credits, drawn before paid credits; null when the account may not draw free credits (its email address is not confirmed, or its free credits were withdrawn) and for a key with no account.
`paid_balance_credits`	integer \| null	Paid credits: bought or granted to the account, drawn once this month's free credits are used up, and never reset; null only for a key with no account (the public sandbox key).
`credits_spent_by_kind`	object	Credits charged within the period, by the kind that paid.

{
  "balance_credits": 91,
  "period": {
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z"
  },
  "scans": {
    "total": 12,
    "billed": 9,
    "by_status": {
      "recognized": 9,
      "no_document_found": 1,
      "unreadable": 1,
      "unsupported_document": 1,
      "rejected": 0
    }
  },
  "credits_spent": 9,
  "free_allowance": {
    "monthly_credits": 100,
    "remaining_credits": 91,
    "resets_at": "2026-10-01T00:00:00Z"
  },
  "paid_balance_credits": 0,
  "credits_spent_by_kind": {
    "free": 9,
    "paid": 0
  }
}

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

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

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