---
title: "Get Token Usage"
method: GET
path: "/api/token_usage"
---

# Get Token Usage

`GET /api/token_usage`

Get token usage aggregated into 15-minute buckets by user and model.

Returns usage broken down by:
- input_tokens: Total input tokens
- cached_tokens: Cached input tokens
- new_input_tokens: New input tokens (input - cached)
- output_tokens: Total output tokens
- reasoning_tokens: Reasoning output tokens

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.

## Query parameters

- `user_id` integer, nullable — Filter by user ID (admin only)
- `all_users` boolean — Return data for all users (admin only opt-in)
- `org_id` integer, nullable — Scope to an organization's members (org admin only)
- `model` string, nullable — Filter by model name
- `start_date` string, date-time, nullable — Start date (ISO 8601)
- `end_date` string, date-time, nullable — End date (ISO 8601)

## Response `200`

Successful Response

- AggregatedUsageResponse — Response model for time-bucketed aggregated token usage.
  - `buckets` AggregatedUsageBucket[], required — Usage in 15-minute buckets
    - `time_bucket` string, date-time, required — Start of the 15-minute interval
    - `user_id` integer, required
    - `user_email` string, nullable
    - `user_name` string, nullable
    - `provider` string, nullable
    - `model` string, nullable
    - `request_count` integer, required — Number of requests in this bucket
    - `input_tokens` integer, required — Total input tokens
    - `cached_tokens` integer, required — Cache read tokens (reduced rate)
    - `cache_write_tokens` integer — Cache write tokens (Anthropic only, 1.25x input rate)
    - `new_input_tokens` integer, required — Uncached input tokens (provider-dependent derivation)
    - `output_tokens` integer, required — Total output tokens
    - `reasoning_tokens` integer, required — Reasoning tokens (subset of output_tokens)
    - `cost_usd` number — Provider cost in USD (summed request_cost_usd)
  - `total_input_tokens` integer, required
  - `total_cached_tokens` integer, required
  - `total_cache_write_tokens` integer, required
  - `total_new_input_tokens` integer, required
  - `total_output_tokens` integer, required
  - `total_reasoning_tokens` integer, required
  - `total_cost_usd` number

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/quadrillion/apis/quadrillion-cloud-api.md) · [All operations](https://skmtc.net/quadrillion/apis/quadrillion-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/quadrillion/quadrillion-cloud-api/revisions/399077308c86/schema)