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

200

The usage report for the requested period.

Errors

Every error uses the typed error envelope.

ErrorMeaningRetryable
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.

3 child fields

typestring

The kind of period.

trial
The free trial.
subscription
A paid subscription's billing period.

startdate-time

When the period starts.

enddate-time

When the period ends.

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.

included_pagesinteger

Pages the plan includes in this period.

One of10050030000

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

accounting_entity_idstring

The entity you filtered by.

Length
1–255 characters

processed_pagesinteger

Processed pages attributed to it in this period.

Trial and plan allowances