Sign in
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": [] }.

Attribution (metering mode): groupBy=profile|account adds an attribution breakdown of the window's spend per profile or account, assembled from your own records and pro-rated against the invoice so sum(groups) + unattributed equals totals exactly. profileId / accountId instead project the whole payload (days, totals, lineItems) onto that one group; peaks, callUsage and tax are then null (workspace-level facts). Projected days spread the group's period share over each day (usage is attributed per period, not per day). Profile-scoped API keys and members only see their profiles' groups (attribution.restricted: true, with totals summing the visible groups). Credits, 10DLC fees and Verify are always unattributed. profileId / accountId on their own do not select metering mode: pair them with range.

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.

groupBy'profile' | 'account'

Metering mode. Adds attribution: the window's spend split per profile or per account (keys are ids; resolve names via GET /v1/profiles / GET /v1/accounts).

profileIdstring

Metering mode (pair with range). Project the payload onto this profile's attributed share. Mutually exclusive with accountId, and groupBy (if given) must be profile; 404 when the profile is not in your workspace (or outside a scoped key's profiles).

accountIdstring

Metering mode (pair with range). Project the payload onto this account's attributed share. Mutually exclusive with profileId, and groupBy (if given) must be account; 404 when the account is not visible to the caller.

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
    }
  }
}

Changes

Changed in 1 of the 26 revisions of this API.25

  • e6f7a453bfb125See the full diff
    • ▲

      the response property oneOf[UsageMetering]/callUsage became nullable for the status 200

      response-property-became-nullable

    • ▲

      the response property oneOf[UsageMetering]/peaks became nullable for the status 200

      response-property-became-nullable

    • ○

      added the new optional query request parameter accountId

      new-optional-request-parameter

    • ○

      added the new optional query request parameter groupBy

      new-optional-request-parameter

    • ○

      added the new optional query request parameter profileId

      new-optional-request-parameter

    • ○

      added the optional property oneOf[UsageMetering]/attribution to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property oneOf[UsageMetering]/scope to the response with the 200 status

      response-optional-property-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog