Sign in

Get Token Usage

Get token usage aggregated into time buckets (15 minutes by default) by user and model.

Returns usage broken down by:

  • input_tokens: Total input tokens as the provider reported them
  • cached_tokens: Cache read tokens
  • cache_write_tokens: Cache write tokens
  • new_input_tokens: Input tokens billed at the full input rate
  • output_tokens: Total output tokens
  • reasoning_tokens: Reasoning output tokens (subset of output_tokens)
  • billable_tokens: Every charged token, comparable to a provider console

Defaults to the caller's own data. Admin users (with @quadrillion.io email) may opt into cross-user data by passing user_id (specific user) or all_users=true (everyone). Non-admin requests for other users' data are silently scoped to the caller.

Passing org_id scopes the response to that organization's members and takes precedence over user_id/all_users. It requires platform admin or org admin/owner access (403 otherwise) and includes member identity in buckets.

The internal dashboard, identified by its workload token rather than a user, reads every account's usage without identity and cannot scope to an organization.

get/api/token_usage

Query parameters

user_idinteger nullable

Filter by user ID (admin only)

Filter by user ID (admin only)

all_usersboolean

Return data for all users (admin only opt-in)

Return data for all users (admin only opt-in)

org_idinteger nullable

Scope to an organization's members (org admin only)

Scope to an organization's members (org admin only)

modelstring nullable

Filter by model name

Filter by model name

attributionstring nullable

Filter by opt-in attribution tag. Normalized like the stored tag, so 'HSBC Demo' matches rows written as 'hsbc-demo'.

Filter by opt-in attribution tag. Normalized like the stored tag, so 'HSBC Demo' matches rows written as 'hsbc-demo'.

start_datestring date-time nullable

Start date (ISO 8601)

Start date (ISO 8601)

end_datestring date-time nullable

End date (ISO 8601)

End date (ISO 8601)

attribution_prefixstring nullable

Keep only tags starting with this, e.g. 'benchmark'. Normalized before matching, preserving trailing '/' or '-'.

Keep only tags starting with this, e.g. 'benchmark'. Normalized before matching, preserving trailing '/' or '-'.

bin_minutesinteger

Width of each time bucket

Width of each time bucket

Response

Successful Response

total_input_tokensinteger required
total_cached_tokensinteger required
total_cache_write_tokensinteger required
total_new_input_tokensinteger required
total_output_tokensinteger required
total_reasoning_tokensinteger required
total_billable_tokensinteger
total_cost_usdnumber

Changes