Skip to main content
GET
Retrieve organization usage and credit status

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 by day, week, or month, ready to chart or feed into internal reporting.
Authentication uses your regular API key (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 fromto window.

Choosing a window

  • Both dates accept YYYY-MM-DD or a full ISO 8601 datetime.
  • With no parameters, the window is the last 30 days.
  • A date-only to is inclusive: to=2026-07-14 covers all of July 14 (UTC).
  • The maximum window is 366 days; longer windows return a 400.
  • by_period buckets 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

Fields that don’t apply to your plan are 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):
A specific month, bucketed by week:
Alerting when the billing period runs hot:

Errors

Authorizations

x-api-key
string
header
required

Query Parameters

from
string

Window start as YYYY-MM-DD or an ISO 8601 datetime. Defaults to 30 days before to.

Example:

"2026-07-10"

to
string

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.

Example:

"2026-07-14"

group_by
enum<string>
default:day

Bucket size for the by_period timeline.

Available options:
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.

from
string<date-time>
required

Resolved window start (UTC).

to
string<date-time>
required

Resolved window end (UTC, inclusive).

group_by
enum<string>
required

Bucket size used for by_period.

Available options:
day,
week,
month
generated_at
string<date-time>
required

When this summary was computed.

billing
object
required

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.

totals
object
required

Consumption over exactly the requested fromto window.

by_period
object[]
required

Usage bucketed by group_by, ascending. Periods with no usage are omitted rather than returned as zero rows.