> ## 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. Other members, including
viewers, see only usage from Routes keys they created, including keys
that have since expired, been revoked, or been deleted. Model API costs
use your prices at the time of each request. 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 has no cost estimate. Costs for OpenAI,
Anthropic, and xAI estimate what you pay those providers; they are not
Baseten charges. A null cost means some usage in that result could not
be priced. 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: 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:
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.
schema:
items:
$ref: '#/components/schemas/RouteUsageDimensionV1'
title: Group By
type: array
- name: api_key_prefixes
in: query
required: false
description: >-
Return only usage for these exact Routes key prefixes, repeated once
per prefix.
schema:
items:
type: string
title: Api Key Prefixes
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: route_ids
in: query
required: false
description: Return only usage for these route IDs, repeated once per ID.
schema:
items:
type: string
title: Route 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, 'start_date': None, 'end_date': None}
)
print(response.text)
components:
schemas:
RouteUsageDimensionV1:
enum:
- API_KEY_PREFIX
- USER
- ROUTE
- MODEL
- PROVIDER
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:
api_key_prefix:
anyOf:
- type: string
- type: 'null'
default: null
description: Prefix of the Routes key. Null when not grouping by API_KEY_PREFIX.
title: Api Key Prefix
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 or when the creator is unknown.
title: User Id
route_id:
anyOf:
- type: string
- type: 'null'
default: null
description: Route ID. Null when not grouping by ROUTE.
title: Route Id
route_name:
anyOf:
- type: string
- type: 'null'
default: null
description: Route name. Null when not grouping by ROUTE.
title: Route Name
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 or when the provider cannot be determined.
cost_usd:
anyOf:
- type: string
- type: 'null'
description: >-
Estimated cost in USD, returned as an exact decimal string. Null
when some usage in this result could not be priced, including all
Vertex and OpenAI-compatible usage. Costs for OpenAI, Anthropic, and
xAI estimate what you pay those providers; they are not Baseten
charges.
examples:
- '0.00035625'
title: Cost Usd
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
request_count:
description: Number of requests.
title: Request Count
type: integer
required:
- cost_usd
- input_tokens
- cached_input_tokens
- uncached_input_tokens
- output_tokens
- request_count
title: RoutesUsageResultV1
type: object
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Send `Authorization: Bearer `. The legacy `Authorization:
Api-Key ` scheme is also accepted.
````