Sign in

v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
Usage

Usage snapshot (default) or billed-spend metering (with params)

Dual-mode endpoint, selected by query params — fully backward compatible:

Without metering params (the default): the plan / quota / usage snapshot — plan name, billing period, limits, usage counts, access state. Identical to GET /v1/usage-stats. Existing integrations keep working unchanged.

With range, granularity, from, or to: usage METERING — billed spend (USD) by product family (accounts, numbers, calls, sms, dlc, xApi, credits, other) over the window, at day / month / total granularity, from Metronome's invoice breakdown (the CHARGE view — always reconciles with what gets billed). Also served at GET /v1/usage/daily. Usage-based accounts only — legacy Stripe accounts get { "supported": false, "days": [] }.

For per-domain consumption volumes use GET /v1/usage/calls and GET /v1/usage/sms. For the billing statement (balance, credits, caps, payment status) use GET /v1/billing.

get/v1/usage

Query parameters

reconcileboolean

Snapshot mode only. For Stripe subscription users, true forces a subscription reconciliation pass even when cached plan data looks complete.

range'cycle' | 'prev-cycle' | '7d' | '14d' | '30d' | '3mo' | '12mo' | 'custom'

Window to report. cycle / prev-cycle resolve to the customer's real billing-period bounds (falling back to a trailing 30 days when no invoice exists yet); 7d…12mo are trailing windows; custom uses from / to.

fromstring date

Inclusive start (UTC date). Required when range=custom.

tostring date

Inclusive end (UTC date). Required when range=custom. Max span 366 days.

granularity'day' | 'month' | 'total'

Bucketing of the days series: day (one row per UTC day), month (one row per calendar month, dated to the 1st), or total (no series — read totals). Does not affect totals.

Response

Snapshot (no metering params) or billed spend by product over the window (with metering params).

OR

Example response

{
  "usage": {
    "xApiCallsByOperation": {
      "posts_read": 42,
      "content_create": 7,
      "content_create_with_url": 3,
      "dm_interaction_create": 1
    }
  }
}