Usage Tracking API
Get usage summary
Returns a high-level usage summary for a period: total event count plus per-metric totals. Call it with a GET request to /usage/summary, authenticated with a restricted API key and the "usage:read" scope.
Returns a high-level usage summary for a period: total event count plus per-metric totals. For cost totals, use GET /cost-data/summary. 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 summary period. 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. |
end_date | query | string | Yes | End of the summary period. ISO 8601 date or datetime. Must be strictly after start_date. |
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 |
|---|---|---|
user_id | string | Bear Lumen account user ID (UUID) that owns the queried usage: the user your API key belongs to. Not the end-user user_id you send on POST /usage-events. |
period_start | string | Start of the period. |
period_end | string | End of the period. |
total_events | number (double) | Total number of events. |
metrics | object[] | Summary by metric. |
metric_name | string | Metric name, stored lowercase (e.g. 'tokens'). |
total_quantity | number (double) | Total quantity consumed for this metric in the period. |
event_count | number (double) | Number of events recorded for this metric in the period. |
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 and start_date is strictly before end_date. |
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. |
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.