Skip to main content
GET
cURL
This endpoint is experimental and may change or be removed without notice.

Authorizations

Authorization
string
header
required

Send Authorization: Bearer <api_key>. The legacy Authorization: Api-Key <api_key> scheme is also accepted.

Query Parameters

cursor
string | null

Opaque cursor returned by a previous page. Omit to fetch the first page.

limit
integer
default:7

Number of daily buckets to return. Defaults to 7; maximum 31.

Required range: 1 <= x <= 31
start_date
string<date> | null

Inclusive UTC calendar day at the start of the query range. Defaults to the previous UTC date, and is ignored when you pass a cursor.

end_date
string<date> | null

Exclusive UTC calendar day at the end of the query range. Defaults to the day after the current UTC date so current-day usage is included.

group_by
enum<string>[]

Dimensions to break usage down by, repeated once per dimension: API_KEY_PREFIX, USER, ROUTE, MODEL, or PROVIDER. Each result represents one observed combination of the requested dimensions within that day, and results are sorted by those values. Combinations without usage are omitted, so result counts can differ between days. Defaults to MODEL.

Available options:
API_KEY_PREFIX,
USER,
ROUTE,
MODEL,
PROVIDER
api_key_prefixes
string[]

Return only usage for these exact Routes key prefixes, repeated once per prefix.

user_ids
string[]

Return only usage from Routes keys created by these user IDs, repeated once per ID.

route_ids
string[]

Return only usage for these route IDs, repeated once per ID.

models
string[]

Return only usage for these exact model names, repeated once per model.

providers
enum<string>[]

Return only usage for these providers, repeated once per provider.

Upstream provider of a route target, named like the route target types.

Available options:
BASETEN_MODEL_API,
OPENAI,
ANTHROPIC,
XAI,
VERTEX,
OPENAI_COMPATIBLE

Response

200 - application/json
items
RoutesUsageBucketV1 · object[]
required

Items in this page.

pagination
PaginationResponseV1 · object
required

Pagination metadata for the page.