GET /v1/organizations/usage_report/messages — the usage half of Anthropic's Usage & Cost Admin API — returns token consumption for your organization in time buckets, optionally grouped and filtered along nine dimensions. It requires an Admin API key (see the key types guide). Used well, it replaces a pile of ad-hoc spreadsheets; used naively, it returns one undifferentiated total. This article maps each dimension to the question it answers.
Time buckets first
Every query picks a bucket_width: 1m, 1h, or 1d. Defaults and maximums per request differ by width — minute buckets return 60 by default (max 1440), hourly 24 (max 168), daily 7 (max 31) — with has_more/next_page pagination beyond that. Minute granularity suits incident forensics ("what exactly happened at 14:03?"), hourly suits capacity work, daily suits finance. Each bucket reports uncached_input_tokens, cache_creation (split into 5-minute and 1-hour TTL cache writes), cache_read_input_tokens, output_tokens, and server_tool_use.web_search_requests.
The nine group_by dimensions
| Dimension | Question it answers |
|---|---|
workspace_id | Which team/project consumed what — the backbone of per-workspace chargeback |
api_key_id | Which credential drove the usage — finds runaway jobs and orphaned keys |
model | Model-level rollup — is spend shifting from Haiku to Opus? |
service_tier | Standard vs batch vs priority (and flex variants) — checks your discount strategy is actually used |
context_window | Usage in the 0-200k vs 200k-1M window bands — long-context traffic has different economics |
inference_geo | Where inference ran (us, global) — data-residency verification from billing-grade data |
speed | Fast mode vs standard requests (beta; see below) |
account_id | Attribution by user account |
service_account_id | Attribution by service account (non-human identities) |
Dimensions compose: grouping by workspace_id + model gives each team's model mix in one query. Filters mirror the dimensions — workspace_ids[], api_key_ids[], models[], service_tiers[], context_window[], inference_geos[], speeds[], account_ids[], service_account_ids[] — so any grouping can also be narrowed to a subset.
import httpx
r = httpx.get(
"https://api.anthropic.com/v1/organizations/usage_report/messages",
headers={"x-api-key": ADMIN_KEY, # sk-ant-admin01-...
"anthropic-version": "2023-06-01"},
params={"starting_at": "2026-07-01T00:00:00Z",
"bucket_width": "1d",
"group_by[]": ["workspace_id", "model"]},
)
for bucket in r.json()["data"]:
print(bucket)Three dimensions with fine print
speed needs a beta header. Grouping by speed or filtering speeds[] (fast / standard) requires the fast-mode-2026-02-01 beta header on the request. Fast mode itself is a first-party-only research preview, so this dimension is only meaningful for 1P traffic — if you never opted into fast mode, skip it.
inference_geo has a historical floor. Models released before February 2026 — anything earlier than the Opus/Sonnet 4.6 generation — report "not_available" for this dimension. A residency-verification report over a mixed model estate should treat not_available as "predates the dimension," not as a compliance red flag. Also note rate limits are shared across geos: us and global draw from one pool.
Attribution has documented gaps. Usage from the Console Workbench carries api_key_id: null, and the default workspace appears as workspace_id: null — build your chargeback queries to expect nulls rather than dropping those rows silently. Per-user Claude Code cost breakdowns need the separate Claude Code Analytics API. Details in Usage API attribution gaps.
bucket_width=1d, group_by[]=workspace_id&group_by[]=model. That single query covers chargeback, model-mix drift, and month-over-month growth; add dimensions only when a concrete question demands them.Freshness and polling
Usage data typically appears within about five minutes of request completion, and the supported sustained polling rate is once per minute. That makes the endpoint suitable for near-real-time dashboards and hourly cost guards, but not for per-request enforcement — anything that must react instantly should read the usage object in each API response instead.
Where to go next
The other half of the API — dollars rather than tokens — is covered in the cost endpoint's mechanics. For turning workspace groupings into an internal billing process, see building a chargeback model. Note this API is a first-party facility: on Claude Platform on AWS it is unavailable (see the Platform-on-AWS exclusion), and Bedrock, Vertex, and Foundry use their clouds' native telemetry.