# Usage

Limits are pooled across the account (SPEC §3.1), so usage is reported for the whole account, with an optional breakdown per project. Totals are refreshed every 5 minutes. Requests are counted exactly, one by one; the other metrics come from usage sampling, accurate to within a few percent.

## `GET /v1/usage`

Who: everyone in the account. Tokens may call it too.

Query: `projectId` (optional) limits `metrics[].used` to one project; `limit` stays the account's. A project outside your account returns `404 not_found`.

```json
{
  "periodStart": "2026-10-01T00:00:00.000Z",
  "periodEnd": "2026-11-01T00:00:00.000Z",
  "metrics": [
    { "metric": "requestsPerMonth", "used": 4100000, "limit": 5000000, "level": "warn" },
    { "metric": "emailsPerMonth", "used": 15000, "limit": 15000, "level": "capped" },
    { "metric": "fileStorageBytes", "used": 10522669875, "limit": 26843545600, "level": "ok" }
  ]
}
```

- `metrics` lists every capped metric, in a fixed order, including ones at zero: `requestsPerMonth`, `functionCpuMsPerMonth`, `databaseStorageBytes`, `fileStorageBytes`, `emailsPerMonth`, `postgresComputeHoursPerMonth`, `monthlyActiveUsers`, `realtimeConnections`, `vectorRecords`.
- `limit` is your effective limit: your plan plus add-ons.
- `level` is `ok` below 80%, `warn` from 80%, `capped` from 100%, and for Postgres compute `read_only` from 150%. It is the same calculation the platform uses to apply caps.
- `periodStart` and `periodEnd` are your current Stripe billing period.
- Bytes are bytes, CPU is milliseconds, Postgres compute is CU-hours. An always-on Postgres project's own compute hours count against that project first; only the rest counts towards the pooled limit.