> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runledger.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runledger.co/_mcp/server.

# 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](/guides/usage-windows), [pool](/guides/pools) and [spend limit](/guides/spend-limits) 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](/concepts/billing#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.

**`Response: UsageSummary`**

```json title="Response: UsageSummary"
{
  "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](/guides/usage-windows). `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](/guides/pools), 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](/guides/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

| Parameter      | Use                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `member_id`    | Read the windows a `per_member` allowance keeps for one member. Without it those windows are left out                                |
| `subscription` | A subscription other than the active one                                                                                             |
| `credit_type`  | A credit type other than the plan's                                                                                                  |
| `as_of`        | The windows that held a past time, each counted to the window's end. Holds and `spend` are as they stand now, for the current period |

## 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](/guides/customer-view).

## When it fails

| Result                          | Cause                                                      |
| ------------------------------- | ---------------------------------------------------------- |
| `403` with `insufficient_scope` | The key lacks `usage:read`                                 |
| `404` with `resource_not_found` | No customer has that ID                                    |
| `400` with `parameter_invalid`  | A filter such as `member_id` is longer than 128 characters |

[Idempotency and errors](/reference/idempotency-and-errors) lists every code.

## API reference

[Retrieve a usage summary](/api-reference/customers/usage-summary/retrieve).

## Next steps

* [Customer view](/guides/customer-view) shows the same meters without building them.
* [Spend limits](/guides/spend-limits) and [usage windows](/guides/usage-windows) define what the meters show.