Usage Tracking API
Get usage events
Retrieves individual usage events recorded for the account your API key belongs to, within a date range. Call it with a GET request to /usage/events, authenticated with a restricted API key and the "usage:read" scope.
Retrieves individual usage events recorded for the account your API key belongs to, within a date range. Use it to confirm ingested events landed. Supports pagination and filtering by subscription and metric. Events sent via POST /usage-events appear here with eventType `ai.inference` and metricName `tokens`; quantity is total tokens (input plus output). Requests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.
Authentication and scopes
Authenticate with a restricted API key in the Authorization: Bearer <key> header. This endpoint requires the usage:read scope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
start_date | query | string | Yes | Start of the query range. ISO 8601 date or datetime (e.g. 2026-01-01 or 2026-01-01T00:00:00Z). Include an explicit UTC offset; date-only values are interpreted as UTC midnight. Must be strictly before end_date; the range may not exceed 90 days. |
end_date | query | string | Yes | End of the query range. ISO 8601 date or datetime. Maximum range: 90 days. |
subscription_id | query | string | No | Optional: Filter by subscription ID. |
metric_name | query | string | No | Optional: Filter by metric name. Metric names are stored lowercase and matched exactly; pass lowercase values (e.g. tokens). |
limit | query | integer (int32) | No | Optional: Number of events to return (default: 100, max: 1000, must be a positive integer). |
offset | query | integer (int32) | No | Optional: Pagination offset (default: 0, must be zero or a positive integer). |
Response fields
Fields returned in the 200 response body. Nested objects are listed under their parent. A field marked optional may be absent from the body; one marked nullable is always present but its value may be null.
| Field | Type | Description |
|---|---|---|
events | object[] | Array of usage events. |
id | string | Unique event ID (UUID). |
event_type | string | Event type label. Events ingested via POST /usage-events always carry 'ai.inference'. |
metric_name | string | Metric name, stored lowercase. Events ingested via POST /usage-events always carry 'tokens'. |
quantity | number (double) | Quantity consumed. For events ingested via POST /usage-events this is total tokens (input plus output). |
event_timestamp | string | When the event occurred (ISO 8601 UTC). |
metadata | map of string to string optional | Metadata supplied on the usage event, plus mapped attribution keys (provider, feature, agent_id, workflow_id, units). |
total | number (double) | Total number of events matching the query. |
limit | number (double) | Number of events returned in this page. |
offset | number (double) | Offset for pagination. |
Error codes
Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.
| Status | When it happens |
|---|---|
400 | Invalid request parameters. Check that start_date and end_date are valid ISO 8601 dates, start_date is strictly before end_date, the range does not exceed 90 days, and limit is a positive integer no greater than 1000. |
401 | Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY. |
403 | Forbidden. The API key is missing the usage:read scope; create or update a key with that scope. |
404 | Subscription not found or not accessible with this API key. Check the subscription_id value. |
429 | Rate limit or plan quota exceeded. Slow down and retry after the current window resets. |
Rate limits and retries
Rate limit or plan quota exceeded. Slow down and retry after the current window resets.