Get Usage
Programmatic counterpart to the platform usage dashboard. Returns the calling organization’s current billing-period credit status plus document, page, and credit totals with a bucketed timeline over the requested window (default: the last 30 days; maximum window: 366 days).
The response is always scoped to the organization the credentials belong to. There is no way to request another organization’s usage: any organization identifier supplied by the caller is ignored, and the response contains no identifiers of any kind.
Overview
Retrieve your organization’s usage programmatically — the same figures shown on the platform usage dashboard. One call returns three things:billing— where your current billing period stands: plan, credit allowance, credits used and remaining, overage, and metered-cost estimates.totals— documents, pages, and credits consumed over the requested window.by_period— the same consumption bucketed byday,week, ormonth, ready to chart or feed into internal reporting.
x-api-key), and the response is always scoped to the organization that key belongs to — organization identifiers supplied in the query string are ignored, and the response contains no identifiers of any kind.
billing reflects your current billing period regardless of the requested window. totals and by_period cover exactly the from→to window.Choosing a window
- Both dates accept
YYYY-MM-DDor a full ISO 8601 datetime. - With no parameters, the window is the last 30 days.
- A date-only
tois inclusive:to=2026-07-14covers all of July 14 (UTC). - The maximum window is 366 days; longer windows return a
400. by_periodbuckets are UTC calendar periods, sorted ascending. Periods with no usage are omitted rather than returned as zero rows — pad them client-side if your charting needs continuous axes.
Response
billing fields
null: credit_allowance on pure metered billing, and every metered pricing field whenever is_metered is false.
totals and by_period fields
Examples
Last 30 days at daily resolution (all defaults):Errors
Authorizations
Query Parameters
Window start as YYYY-MM-DD or an ISO 8601 datetime. Defaults to 30 days before to.
"2026-07-10"
Window end as YYYY-MM-DD or an ISO 8601 datetime. A date-only value is inclusive — it extends to the end of that day (UTC). Defaults to the current time.
"2026-07-14"
Bucket size for the by_period timeline.
day, week, month Response
Usage summary for the calling organization
Organization usage summary: current billing-period credit status plus totals and a bucketed timeline for the requested window. Matches the figures shown on the platform usage dashboard.
Resolved window start (UTC).
Resolved window end (UTC, inclusive).
Bucket size used for by_period.
day, week, month When this summary was computed.
Where the organization's current billing period stands. Reflects the active plan and billing cycle regardless of the requested window. Fields that don't apply to the plan are null — the allowance on pure metered billing, and every metered pricing field (metered_rate, estimated_cost, overage_cost) unless is_metered is true.
Consumption over exactly the requested from→to window.
Usage bucketed by group_by, ascending. Periods with no usage are omitted rather than returned as zero rows.