v54

OpenAPI 3.1.0raw.githubusercontent.com2026-08-038690315.6 KB

usage

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), the error taxonomy grouped by failure status code, and a UTC-bucketed time series.

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.

get/v1/usage/summary

Query parameters

start_datestring date-time nullable

Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)

Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)

end_datestring date-time nullable

Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)

Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)

user_idstring nullable

Filter to a single user

Filter to a single user

statusstring nullable

Filter to a single status (e.g. 'success' or 'error')

Filter to a single status (e.g. 'success' or 'error')

status_codeinteger nullable

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

modelstring nullable

Filter to a single model

Filter to a single model

endpointstring nullable

Filter to a single endpoint (e.g. '/v1/chat/completions')

Filter to a single endpoint (e.g. '/v1/chat/completions')

providerstring nullable

Filter to a single provider (e.g. 'openai')

Filter to a single provider (e.g. 'openai')

sourcestring nullable

Filter to a single provenance source (e.g. 'gateway' or 'claude_code')

Filter to a single provenance source (e.g. 'gateway' or 'claude_code')

source_labelstring nullable

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)

api_key_idstring nullable

Filter to a single API key id

Filter to a single API key id

pricedboolean nullable

Filter by pricing state: true = only rows with a cost, false = only unpriced rows (cost is null)

Filter by pricing state: true = only rows with a cost, false = only unpriced rows (cost is null)

counts_toward_budgetboolean nullable

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

bucket'hour' | 'day'

Time-series granularity: 'hour' or 'day'

Time-series granularity: 'hour' or 'day'

dimensionsstring[] nullable

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

bucket'hour' | 'day' required

end_datestring required

start_datestring required