Usage meters

GET /v1/customers/{customer_id}/usage_summary returns what a usage meter in your product needs in one call: every window that applies to the customer, the balance pools, the next credits to expire, this period’s spend and the spend limits in force.

Before you start

• A customer with a subscription. The summary shows every usage window, pool and spend limit that applies. A plan with none still returns one window and one pool.
• A key with the usage:read scope.

It reads from the ledger, so it works for every customer. A customer on a plan with no allowances gets one window for the plan period and one pool.

{
  "object": "usage_summary",
  "customer": "cus_9sF2kq81LmQz",
  "subscription": "sub_5gT8hY1uIo",
  "credit_type": "ai_credits",
  "as_of": "2026-11-04T13:12:09Z",
  "windows": [
    {
      "key": "monthly",
      "kind": "refill",
      "pool": "included",
      "scope": "customer",
      "window": { "type": "fixed", "duration": "P1M" },
      "period_start": "2026-11-01T00:00:00Z",
      "resets_at": "2026-12-01T00:00:00Z",
      "granted": "5000",
      "used": "4430",
      "held": "40",
      "remaining": "530",
      "percent_used": "0.886"
    },
    {
      "key": "session",
      "kind": "cap",
      "pool": "included",
      "scope": "customer",
      "window": { "type": "session", "duration": "PT5H" },
      "period_start": "2026-11-04T10:00:00Z",
      "resets_at": "2026-11-04T15:00:00Z",
      "granted": "1500",
      "used": "930",
      "held": "40",
      "remaining": "530",
      "percent_used": "0.62"
    }
  ],
  "pools": [
    { "pool": "included", "posted": "570", "held": "40", "available": "530" },
    {
      "pool": "purchased",
      "posted": "4300",
      "held": "0",
      "available": "4300",
      "next_expiry": { "amount": "1000", "at": "2027-01-15T00:00:00Z" }
    }
  ],
  "spend": {
    "this_period": { "amount": 1230, "currency": "usd" },
    "basis": "cost_basis",
    "period_start": "2026-11-01T00:00:00Z",
    "resets_at": "2026-12-01T00:00:00Z"
  },
  "binding_window": "session",
  "livemode": false
}

Read it

• windows has one entry for each allowance. granted is the credits granted in the window, or the cap for a cap. percent_used is used over granted as a decimal from 0 to 1, so "0.62" is 62%. held is active holds, counted in remaining and not in percent_used.
• binding_window is the key of the window with the least room left. Draw that one as the headline meter, because it is the one that will stop the customer first.
• pools is the balance split by pool, with the next credits in each pool to expire.
• spend is the money value of this period’s consumption. basis is cost_basis for prepaid plans, where credits are valued at the cost basis of the grants they came from, and charges for postpaid plans, where it is the total of the lines on the period’s draft invoice so far: the recurring fee is in it, and a pending outcome charge isn’t until it confirms.
• spend_limits lists the spend limits that apply, each with what has been spent against it.

A postpaid plan has no credits. Its windows hold one entry for each usage rate with an included_quantity, with kind: included, and its pools are empty.

Parameters

Don’t decide with it

Use the summary to draw meters, not to decide whether work may start. Summaries and lists can lag by a few seconds. check() is the authority, and it serializes against the same ledger, so it never allows work the summary would show as over.

To show customers the same meters without building them, send them to the customer view.

When it fails

Idempotency and errors lists every code.

API reference

Retrieve a usage summary.

Next steps

• Customer view shows the same meters without building them.
• Spend limits and usage windows define what the meters show.