The Usage API returns one project's usage for a calendar month. Use it to show usage inside your own app, check how close a project is to an allowance, or reconcile what you bill your own customers.
It uses the same project API key as /v1/ai (Authorization: Bearer mr_live_…) and only ever returns that key's project.
Get usage for a month
1GET /v1/usage?month=2026-10| Parameter | Default | Notes |
|---|---|---|
month | the current month | YYYY-MM, in UTC. The current month and the 24 before it |
1{2 "project_id": "7c2e5a0b-3f41-4f7e-9d0a-6a1b2c3d4e5f",3 "month": "2026-10",4 "period_start": "2026-10-01T00:00:00Z",5 "period_end": "2026-11-01T00:00:00Z",6 "billable_requests": 3240,7 "requests": 3301,8 "failed_requests": 12,9 "prompt_tokens": 4120000,10 "completion_tokens": 610000,11 "total_tokens": 4730000,12 "price": 12.48,13 "active_sessions": 980,14 "by_day": [15 { "date": "2026-10-01", "billable_requests": 112, "requests": 115 },16 { "date": "2026-10-02", "billable_requests": 98, "requests": 98 }17 ],18 "updated_at": "2026-10-27T09:14:00Z"19}| Field | Description |
|---|---|
billable_requests | Requests that count toward your plan, counted the same way as billing |
requests | All requests, including Playground and test-mode runs |
failed_requests | Requests that ended in an error |
prompt_tokens, completion_tokens, total_tokens | Tokens across all requests |
price | Estimated provider cost in USD, from ModelRiver's model pricing |
active_sessions | Distinct sessions with at least one request in the month |
by_day | Every day of the month up to today (UTC), including days with no requests |
updated_at | When these numbers were counted |
What counts as a billable request
- Each
/v1/airequest counts once, even when failover retried it on another provider. - Playground and test-mode runs don't count.
- Messages added with
POST /v1/sessions/:id/messagesdon't count: they never call a model.
How current it is
The current month includes requests made up to a minute ago. Results are cached for about a minute per project and month, so polling faster than that returns the same numbers; check updated_at.
Usage for earlier months stays available after request logs are removed at the end of your plan's retention period. A request that finishes late, such as an async callback, can still change the last few days of a month for up to a week.
Errors
A month that isn't YYYY-MM, is in the future, or is more than 24 months back returns 422:
1{ "error": "invalid_month", "message": "month must be YYYY-MM, from 2024-10 to 2026-10" }A missing or invalid API key returns 401.
Next steps
- Sessions API: Read, extend and follow conversations
- Authentication: Create and rotate API keys
- Error handling: Status codes and retries