> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Get route usage
> Gets daily route usage and estimated costs.
This endpoint is experimental and may change or be removed without notice.
## OpenAPI
````yaml get /v1/routes/usage
openapi: 3.1.0
info:
description: REST API for management of Baseten resources
title: Baseten management API
version: 1.0.0
servers:
- url: https://api.baseten.co
security:
- BearerAuth: []
paths:
/v1/routes/usage:
get:
summary: Gets daily route usage and estimated costs
description: >-
Buckets are UTC days, and days with no usage are included. Organization
admins see all route usage in the organization. Team admins see usage in
teams they manage. Other members, including viewers, see only usage from
Routes keys they created, including keys that have since expired, been
revoked, or been deleted. Usage can be filtered and grouped by the team
it was metered in. Usage is metered every 15 minutes, so the current
hour can lag. Model API costs use your prices at the time of each
request and include tool calls. xAI costs are the charges xAI reports.
OpenAI and Anthropic costs are estimated from Baseten's reference prices
and may differ from your provider's bill. Vertex and OpenAI-compatible
usage is not included. Costs for OpenAI, Anthropic, and xAI estimate
what you pay those providers; they are not Baseten charges. Usage is
retained for 92 days.
parameters:
- name: cursor
in: query
required: false
description: >-
Opaque cursor returned by a previous page. Omit to fetch the first
page.
schema:
anyOf:
- type: string
- type: 'null'
default: null
title: Cursor
- name: limit
in: query
required: false
description: Number of daily buckets to return. Defaults to 7; maximum 31.
schema:
default: 7
maximum: 31
minimum: 1
title: Limit
type: integer
- name: team_id
in: query
required: false
description: >-
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.
schema:
anyOf:
- type: string
- type: 'null'
default: null
title: Team Id
- name: start_date
in: query
required: false
description: >-
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.
schema:
anyOf:
- format: date
type: string
- type: 'null'
default: null
title: Start Date
- name: end_date
in: query
required: false
description: >-
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.
schema:
anyOf:
- format: date
type: string
- type: 'null'
default: null
title: End Date
- name: group_by
in: query
required: false
description: >-
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.
schema:
items:
$ref: '#/components/schemas/RouteUsageDimensionV1'
title: Group By
type: array
- name: user_ids
in: query
required: false
description: >-
Return only usage from Routes keys created by these user IDs,
repeated once per ID.
schema:
items:
type: string
title: User Ids
type: array
- name: models
in: query
required: false
description: >-
Return only usage for these exact model names, repeated once per
model.
schema:
items:
type: string
title: Models
type: array
- name: providers
in: query
required: false
description: Return only usage for these providers, repeated once per provider.
schema:
items:
$ref: '#/components/schemas/RouteProviderV1'
title: Providers
type: array
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/RoutesUsageResponseV1'
x-codeSamples:
- lang: bash
source: |
curl --request GET \
--url https://api.baseten.co/v1/routes/usage \
--header "Authorization: Bearer $BASETEN_API_KEY"
- lang: python
source: |-
import requests
import os
API_KEY = os.environ.get("BASETEN_API_KEY", "")
url = "https://api.baseten.co/v1/routes/usage"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.request(
"GET",
url,
headers=headers,
params={'cursor': None, 'team_id': None, 'start_date': None, 'end_date': None}
)
print(response.text)
components:
schemas:
RouteUsageDimensionV1:
enum:
- USER
- TEAM
- MODEL
- PROVIDER
- ROUTER
title: RouteUsageDimensionV1
type: string
RouteProviderV1:
description: Upstream provider of a route target, named like the route target types.
enum:
- BASETEN_MODEL_API
- OPENAI
- ANTHROPIC
- XAI
- VERTEX
- OPENAI_COMPATIBLE
title: RouteProviderV1
type: string
RoutesUsageResponseV1:
properties:
items:
description: Items in this page.
items:
$ref: '#/components/schemas/RoutesUsageBucketV1'
title: Items
type: array
pagination:
$ref: '#/components/schemas/PaginationResponseV1'
description: Pagination metadata for the page.
required:
- items
- pagination
title: RoutesUsageResponseV1
type: object
RoutesUsageBucketV1:
properties:
date:
description: >-
UTC calendar date for this bucket, from midnight inclusive to the
next midnight exclusive.
format: date
title: Date
type: string
results:
description: >-
Usage broken down by the requested dimensions. Empty when there is
no usage.
items:
$ref: '#/components/schemas/RoutesUsageResultV1'
title: Results
type: array
required:
- date
- results
title: RoutesUsageBucketV1
type: object
PaginationResponseV1:
properties:
has_more:
description: Whether more items exist after this page.
title: Has More
type: boolean
cursor:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Opaque cursor to pass into the next request. Null when there is no
next page.
title: Cursor
required:
- has_more
title: PaginationResponseV1
type: object
RoutesUsageResultV1:
properties:
user_id:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
ID of the user who created the Routes key. Null when not grouping by
USER.
title: User Id
team_id:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
ID of the team the usage was metered in. Null when not grouping by
TEAM, and for usage metered before it was attributed to teams.
title: Team Id
model:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Model name. For external providers, the model name sent to the
provider. Null when not grouping by MODEL.
title: Model
provider:
anyOf:
- $ref: '#/components/schemas/RouteProviderV1'
- type: 'null'
default: null
description: >-
Provider that served the requests. Null when not grouping by
PROVIDER.
router_id:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
Slug of the intelligent router, matching its name in `GET
/v1/routes`. Null when not grouping by ROUTER.
title: Router Id
cost_usd:
description: >-
Estimated cost in USD, returned as an exact decimal string. Costs
for OpenAI, Anthropic, and xAI estimate what you pay those
providers; they are not Baseten charges.
examples:
- '0.00035625'
title: Cost Usd
type: string
input_tokens:
description: Input tokens, including cached input tokens.
title: Input Tokens
type: integer
cached_input_tokens:
description: Input tokens read from the prompt cache.
title: Cached Input Tokens
type: integer
uncached_input_tokens:
description: >-
Input tokens not read from the prompt cache, including tokens
written to the cache.
title: Uncached Input Tokens
type: integer
output_tokens:
description: Output tokens.
title: Output Tokens
type: integer
requests:
description: >-
Number of requests; with ROUTER, the requests sent through that
router. Usage recorded before requests were counted adds zero.
title: Requests
type: integer
required:
- cost_usd
- input_tokens
- cached_input_tokens
- uncached_input_tokens
- output_tokens
- requests
title: RoutesUsageResultV1
type: object
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Send `Authorization: Bearer `. The legacy `Authorization:
Api-Key ` scheme is also accepted.
````