Usage
Retrieve aggregate spend, request, and token usage for the authenticated API key
Overview
The Usage API returns bounded aggregate usage for the API key used to authenticate the request. Use it to answer:- What did this API key spend?
- Which models was that spend on?
- How many requests and tokens were used?
- What happened over a specific UTC date range?
Base URL
Authentication
Use the same NanoGPT API key authentication as other API routes:Default Request
If no date range is provided, the endpoint returns the authenticated API key’s last 30 UTC days, grouped by both day and model.Date Ranges
Usefrom and to to request an explicit UTC date range. Both values must be YYYY-MM-DD dates. to is inclusive.
fromandtomust be provided together.tomust be on or afterfrom.tocannot be in the future.- Ranges are capped at 366 days.
- All dates are interpreted in UTC.
Grouping
Usegroup_by to control which aggregate arrays are returned.
day,model is the default. model,day is accepted as an alias for day,model.
Example:
Scope
The endpoint is scoped to the authenticated API key.Response Shape
Field Reference
Top-level fields:modelvalues are public model labels.- Internal routing providers are not exposed.
- Variants that share the same public label may be combined under that label.
Refund Notes
Refunds are applied at each returned aggregation level with:byModel or byDayModel rows may differ slightly from totals.netCostUsd when refunds cross buckets.
Errors
Errors use the standard NanoGPT API error shape:Legacy Parameter Behavior
The usage endpoint is aggregate-first and rejects legacy row-history parameters. Rejected legacy parameters include:durationpagepageSizesortdirfilterweekOffsettzinclude_summary
from and to dates instead.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
UTC start date in YYYY-MM-DD format. Must be provided together with to.
"2026-05-01"
UTC end date in YYYY-MM-DD format, inclusive. Must be on or after from and cannot be in the future.
"2026-05-31"
Controls which aggregate arrays are returned. model,day is accepted as an alias for day,model.
day, model, day,model, model,day "day,model"
Usage scope. current_key and api_key both return usage for the authenticated API key.
current_key, api_key Optional current API key ID. Requests for another API key are rejected.
123
Response
Aggregate usage for the authenticated API key
Always usage.
usage Echoes the requested usage scope.
current_key, api_key UTC start date.
"2026-05-01"
UTC end date, inclusive.
"2026-05-31"
Always UTC.
UTC The effective grouping mode.
day, model, day,model "day,model"
Timestamp when the aggregate response was generated. Cached responses can be up to 60 seconds old.
"2026-05-31T12:00:00.000Z"
Returned when grouped by day.
Returned when grouped by model.
Returned when grouped by both day and model.