Documentation menu

API · Account

Priced usage for a period

GET /api/v1/usage

Defaults to the last 30 days, grouped by SKU. Only the calling key's mode is included, so a test key never shows live spend and vice versa. Amounts are micro-USD; quantity (on rows grouped by sku) is pages for pages.* SKUs and tokens for swift.*, summit.* and compass.* SKUs. Rows grouped by day carry count and amount_micro only.

Query parameters

  • from string optional

    Start of the period. An ISO 8601 datetime, or a plain YYYY-MM-DD date (treated as UTC midnight).

    Example: from=2026-09-01

  • to string optional

    End of the period, same formats, inclusive: a bare date covers the whole of that day. Defaults to now.

    Example: to=2026-09-30

  • group_by sku | day optional default sku

    sku to see what you are spending it on, day to see it over time.

    Example: group_by=day

Returns 200

Charges for the period, grouped.

  • object string

    Always usage.

  • from string

    Start of the period.

  • group_by sku | day

    How rows are grouped.

  • mode live | test

    The calling key's mode; only its usage is counted.

  • rows array of object

    One per SKU or day.

    4 fields
    • amount_micro integer

      Charged, in micro-USD.

    • count integer

      How many usage records.

    • key string

      The SKU (like pages.layout) or the day (YYYY-MM-DD).

    • quantity integer

      Pages for pages.* SKUs, tokens for the rest.

  • to string

    End of the period.

  • total object

    The whole period.

    1 fields
    • amount_micro integer

      Total charged, in micro-USD.

Errors

  • 401

    Missing, revoked or expired key
  • 422

    Body or options failed validation (details lists the fields), or the document is too large (document_too_large)
  • 429

    Per-second burst limit for the plan exceeded; retry after Retry-After seconds

Every error has the same shape. See Errors.