Usage Summary
Aggregate spend, tokens, and request volume for the dashboard Usage page.
Range-bounded (default last 30 days, hard-capped): unlike the raw /v1/usage list, every aggregate is scoped to a bounded window so it stays served by the timestamp index. Returns grand totals, breakdowns by model / user / API key / source / session (source_label) / endpoint / provider (top rows plus a reconciling other fold, billed token counts), the error taxonomy grouped by failure status code, and a UTC-bucketed time series carrying each bucket's error count and billed token composition (input incl. cache, cache read/write, output).
Each breakdown is its own GROUP BY pass, so a caller that reads only the totals or the series should narrow dimensions rather than pay for all eight (the dashboard's tiles, timeline context, and model typeahead all do). Omitting the parameter keeps the full set.
model, user_id, and api_key_id are repeatable: several values match any of them, so one chart can compare a handful of models, users, or keys.
Query parameters
Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)
Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)
Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)
Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)
Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.
Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.
Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)
Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)
Filter to a single failure status code (e.g. 429 for provider rate limits, 402 for missing-pricing rejections). Only error rows carry one, so this filter also restricts to status='error' unless 'status' is given explicitly
Filter to a single failure status code (e.g. 429 for provider rate limits, 402 for missing-pricing rejections). Only error rows carry one, so this filter also restricts to status='error' unless 'status' is given explicitly
Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.
Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.
Filter to a single endpoint (e.g. '/v1/chat/completions')
Filter to a single endpoint (e.g. '/v1/chat/completions')
Filter to a single provider (e.g. 'openai')
Filter to a single provider (e.g. 'openai')
Filter to a single provenance source (e.g. 'gateway' or 'claude_code')
Filter to a single provenance source (e.g. 'gateway' or 'claude_code')
Filter to a single session/project label (the source_label carried by imported usage)
Filter to a single session/project label (the source_label carried by imported usage)
Filter to one or more API key ids; repeatable (api_key_id=a&api_key_id=b). Several values match any of them. At most 50 per call.
Filter to one or more API key ids; repeatable (api_key_id=a&api_key_id=b). Several values match any of them. At most 50 per call.
Filter by token-pricing state: true = only rows whose model tokens were priced, false = only rows that still need pricing (no cost at all, or tokens that were never metered because the model had no rate). A row charged only for gateway-run tool calls still counts as needing pricing.
Filter by token-pricing state: true = only rows whose model tokens were priced, false = only rows that still need pricing (no cost at all, or tokens that were never metered because the model had no rate). A row charged only for gateway-run tool calls still counts as needing pricing.
Filter to requests that ran a gateway-run tool. 'any' matches any tool; a tool name (web_search, code_execution) matches that tool specifically.
Filter to requests that ran a gateway-run tool. 'any' matches any tool; a tool name (web_search, code_execution) matches that tool specifically.
Filter by budget participation: true = only enforced gateway rows, false = only imported rows that never touch a budget
Filter by budget participation: true = only enforced gateway rows, false = only imported rows that never touch a budget
Time-series granularity: 'hour' or 'day'
Time-series granularity: 'hour' or 'day'
Which breakdowns to compute; repeatable (dimensions=model&dimensions=user). Each value names the 'by_<value>' response field it fills, except 'status_code', which fills the failure taxonomy in 'errors_by_status_code'. Omit for every breakdown (the default); pass 'none' for a totals-and-series-only response. Each dimension left out skips one GROUP BY scan, so a caller that reads only the tiles or the time series should say so. Fields that were not requested come back empty.
Which breakdowns to compute; repeatable (dimensions=model&dimensions=user). Each value names the 'by_<value>' response field it fills, except 'status_code', which fills the failure taxonomy in 'errors_by_status_code'. Omit for every breakdown (the default); pass 'none' for a totals-and-series-only response. Each dimension left out skips one GROUP BY scan, so a caller that reads only the tiles or the time series should say so. Fields that were not requested come back empty.
Response
Successful Response