Sign in

v65

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0794109383.7 KB
usage

List Usage

List usage logs ordered by timestamp (most recent first).

Supports optional filters for time range, user, status, failure status code, model, endpoint, provider, source, session (source_label), and request group (request_group_id, repeatable, which returns a routed request's whole attempt plan). Paginated via skip/limit. The return shape is a bare JSON array; external billing/analytics consumers depend on this, so the total row count for a paginated UI is served separately by GET /v1/usage/count rather than wrapped in an envelope here. Timestamps accept either ISO 8601 strings or Unix epoch seconds (numeric).

get/v1/usage

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 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.

statusstring nullable

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)

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 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.

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 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.

pricedboolean nullable

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.

tool'any' | 'web_search' | 'code_execution' nullable

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.

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

request_group_idstring[] nullable

Filter to the rows of one or more request groups; repeatable (request_group_id=a&request_group_id=b). A routed request writes one row per attempt, all sharing a request_group_id, so this returns a request's whole plan: its absorbed attempts and the attempt that served it. Ignore ordering by timestamp and read attempt_position to reconstruct the plan. At most 1000 ids per call.

Filter to the rows of one or more request groups; repeatable (request_group_id=a&request_group_id=b). A routed request writes one row per attempt, all sharing a request_group_id, so this returns a request's whole plan: its absorbed attempts and the attempt that served it. Ignore ordering by timestamp and read attempt_position to reconstruct the plan. At most 1000 ids per call.

skipinteger
limitinteger

Response

Successful Response

api_key_idstring nullable required
api_key_namestring nullable
attempt_countinteger nullable
attempt_positioninteger nullable
billing_metersobject nullable required
cache_read_tokensinteger nullable required
cache_write_1h_tokensinteger nullable required
cache_write_tokensinteger nullable required
completion_tokensinteger nullable required
costnumber nullable required
counts_toward_budgetboolean required
endpointstring required
error_messagestring nullable required
idstring required
latency_msinteger nullable required
modelstring required
policy_namestring nullable
pricing_breakdownobject[] nullable required
prompt_tokensinteger nullable required
providerstring nullable required
request_group_idstring nullable
selection_reasonstring nullable
sourcestring required
source_labelstring nullable required
statusstring required
status_codeinteger nullable required
timestampstring required
total_tokensinteger nullable required
user_aliasstring nullable
user_idstring nullable required