v54

OpenAPI 3.1.0raw.githubusercontent.com2026-08-038690315.6 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, and session (source_label). 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)

end_datestring date-time nullable

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

user_idstring nullable

Filter to a single user

statusstring nullable

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

modelstring nullable

Filter to a single model

endpointstring nullable

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

providerstring nullable

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

sourcestring nullable

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)

api_key_idstring nullable

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)

counts_toward_budgetboolean nullable

Filter by budget participation: true = only enforced gateway rows, false = only imported rows that never touch a budget

skipinteger

limitinteger

Response

Successful Response

api_key_idstring nullable required

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

pricing_breakdownobject[] nullable required

prompt_tokensinteger nullable required

providerstring nullable required

sourcestring required

source_labelstring nullable required

statusstring required

status_codeinteger nullable required

timestampstring required

total_tokensinteger nullable required

user_idstring nullable required