Get route usage

Gets daily route usage and estimated costs.

GET /v1/routes/usage

cURL

cURL

curl --request GET \
--url https://api.baseten.co/v1/routes/usage \
--header "Authorization: Bearer $BASETEN_API_KEY"

200

{
  "items": [
    {
      "date": "2023-12-25",
      "results": [
        {
          "cost_usd": "0.00035625",
          "input_tokens": 123,
          "cached_input_tokens": 123,
          "uncached_input_tokens": 123,
          "output_tokens": 123,
          "requests": 123,
          "user_id": "<string>",
          "team_id": "<string>",
          "model": "<string>",
          "provider": "BASETEN_MODEL_API",
          "router_id": "<string>"
        }
      ]
    }
  ],
  "pagination": {
    "has_more": true,
    "cursor": "<string>"
  }
}

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

team_id · string | null

Limit usage to a team you can access. Organization admins can view all usage in the team, team admins can view usage in teams they manage, and other members can view only their own usage. Without a team, organization admins see all organization usage, team admins see their managed teams, and other members see their own usage.

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: USER, TEAM, MODEL, PROVIDER, or ROUTER. 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. ROUTER returns only usage sent through an intelligent router, one row per router, or per router and model with MODEL. Router rows repeat usage already counted in other groupings, so don't add them to model totals. Defaults to MODEL.

Available options: USER, TEAM, MODEL, PROVIDER, ROUTER

user_ids · string[]

Return only usage from Routes keys created by these user 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.

Show child attributes

pagination · PaginationResponseV1 · object · required

Pagination metadata for the page.

Show child attributes