Get Usage Report

Token usage in time buckets, optionally grouped by model, API key or context window.

Get your token usage over a time range, split into buckets of a minute, an hour or a day. Group the results by model, API key or context window to see where your tokens go.

GET /v1/account/usage

For dollar amounts, use request logs (cost per request) or billing transactions.

Buckets

Bucket edges are aligned to UTC: 1d buckets start at midnight UTC and 1h buckets on the hour. starting_at is rounded down to the start of its bucket.

`bucket_width`	Default `limit`	Max `limit`
`1d`	7	31
`1h`	24	168
`1m`	60	1440

Every bucket in the range is returned, including buckets with no usage (their results is empty). Without ending_at, the report runs up to the bucket that contains the current time.

Query parameters

starting_atstringrequired

Start of the range (RFC 3339), rounded down to the start of its bucket.

ending_atstringoptional

End of the range (RFC 3339), exclusive. Only buckets that end by this time are returned.

bucket_widthstringoptionalDefault 1d

Size of each bucket.

Allowed values:1d1h1m

limitintegeroptional

Number of buckets per page. Default and maximum depend on bucket_width (see Buckets).

pagestringoptional

The next_page token from the previous response.

group_by[]string[]optional

Split each bucket's results by these dimensions. Without it, each bucket has one result with the totals.

Allowed values:modelapi_key_idcontext_window

models[]string[]optional

Only count requests to these models.

api_key_ids[]string[]optional

Only count requests made with these API keys.

context_window[]string[]optional

Only count requests whose input falls in these size ranges.

Allowed values:0-200k200k-1M

Array parameters can be repeated, with or without brackets: models[]=a&models[]=b and models=a&models=b are the same.

Response

dataBucket[]optional

One entry per bucket, oldest first. Each has starting_at, ending_at (RFC 3339) and results.

has_morebooleanoptional

true when more buckets remain in the range.

next_pagestring | nulloptional

Pass as page to get the next buckets.

Result fields

uncached_input_tokensintegeroptional

Input tokens that were neither read from nor written to the prompt cache.

cache_read_input_tokensintegeroptional

Input tokens read from the prompt cache.

cache_creationobjectoptional

Input tokens written to the cache: ephemeral_5m_input_tokens and ephemeral_1h_input_tokens.

output_tokensintegeroptional

Output tokens.

modelstring | nulloptional

The model, when grouped by model.

api_key_idstring | nulloptional

The API key, when grouped by api_key_id.

context_windowstring | nulloptional

0-200k or 200k-1M, when grouped by context_window.

Errors

Status	Reason
`400`	`starting_at` is missing, a timestamp isn't RFC 3339, a value isn't allowed, `limit` is out of range, or `page` is invalid.