Billed usage over a window, broken down by one dimension

Server URLloading...

GET

/v1/usage

Send

Authorization

Query

Reads the durable billing rollup (usage_daily) for the key's organization. totals is the billed quantity; groups plus unattributed equals totals per metric. If they do not, a warnings entry says so; trust totals.

Pitfalls:

• to is EXCLUSIVE. One day 2026-08-01 is from=2026-08-01&to=2026-08-02. Days are UTC.
• Default window: the last 30 UTC days including today. Maximum 400 days per call.
• A key filed under a project is pinned to it: project_id naming another project is 404, and omitting it reads only the key's project. A key with no project may name any project in the org.
• group_by=key returns a different body, UsageByKey: per API key (key_id, name, prefix, project_id, revoked), counters per metric per UTC day, from the per-key rollup. Requests made without a key (the dashboard) are not in it. No caller IPs or countries are returned.
• group_by=engine: the per-engine table is often empty today, so the whole quantity may appear in unattributed with a warning. That is missing attribution, not missing usage.
• group_by=feature cannot attribute requests, engine_ms, byte counters or the non-batch part of credits; they land in unattributed. Batch spend is attributed to the batch group.
• credits is total credit spend, batch items included, in every grouping.
• Check stale_seconds: a large value means the rollup is behind.

Query Parameters

Response Body

curl -X GET "https://example.com/v1/usage"

{  "period": {    "start": "2026-09-01",    "end": "2026-09-03",    "days": 2,    "bounds": "[start, end)"  },  "group_by": "key",  "keys": [    {      "key_id": "01J9Z3K6V1Q2W3E4R5T6Y7U8I9",      "name": "ci-pipeline",      "prefix": "spicrawl_live_a1b2",      "project_id": "01J9Z3K6V1Q2W3E4R5T6Y7U8P0",      "revoked": false,      "days": [        {          "day": "2026-09-01",          "metrics": {            "requests": 120,            "client_cli": 120,            "feature_screenshot": 4          }        }      ],      "totals": {        "requests": 120,        "client_cli": 120,        "feature_screenshot": 4      }    }  ]}