API reference
Retrieve usage
Retrieve current or historical processed-page usage for the account. Pages are counted when processing finishes. Documents still being processed are not included.
On this page
GET/v1/usage
Query parameters
accounting_entity_idstring
Attribute finalized processed pages to one of your accounting entities. This adds an attribution breakdown; account totals stay the same.
- Length
- 1–255 characters
periods_agointeger
A closed billing period to report, counted back from the current one: 1 is the most recently closed retained period. Omit it for the current period.
- Range
- 1–999,999,999
Responses
The usage report for the requested period.
Errors
Every error uses the typed error envelope.
| Error | Meaning | Retryable |
|---|---|---|
400 invalid_request | The request body, headers, query parameters or path did not validate. What to do | No |
401 invalid_api_key | The API key was not accepted. What to do | No |
404 usage_period_not_found | The requested closed billing period does not exist for this account. What to do | No |
429 rate_limit_exceeded | Too many requests. Wait at least Retry-After, then retry a limited number of times. Create and upload-complete enforce rate limits today; the other operations reserve this response. What to do | Yes, after Retry-After |
500 internal_error | Something failed on our side. An HTTP 500 alone does not mean you may retry; check retryable and keep the request ID. What to do | No |
An invalid query combination returns 400 invalid_request; a historical period outside the retained window returns 404 usage_period_not_found.
Response body
Pages count when processing finishes. Paid plans continue into overage instead of stopping at the included pages.
periodobject · nullable
The billing period reported. It is null only when there is no plan.
planstring
The account's plan for this period.
trial- The free trial.
starter- The Starter plan.
pro- The Pro plan.
none- No active plan; every count is zero.
used_pagesinteger
Processed pages counted in this period.
remaining_pagesinteger
Included pages left.
overage_pagesinteger
Pages beyond the included pages, on paid plans.
attributionobjectOptional
Present when accounting_entity_id filters the report: the pages attributed to that entity. Account totals stay authoritative for billing.
2 child fields
processed_pagesinteger
Processed pages attributed to it in this period.