What changed, and what did not
On 29 October 2026 Anthropic launched the Usage and Cost Analytics API in beta. Its /v1/organizations/analytics/usage and /v1/organizations/analytics/cost endpoints report token usage and cost for Claude Console and Claude Enterprise organizations, with filtering and grouping by model, workspace, API key, and the user or service account behind each request. The same release note declared the older Usage and Cost API legacy, along with four Claude Enterprise Analytics API reports: usage_report, cost_report, user_usage_report and user_cost_report. All of them remain supported.1
So this is a planned rebuild, not an outage. The legacy page itself says to use the new API for new integrations, because it reports usage and cost with more grouping and filtering dimensions.2 If a job that pulls /v1/organizations/cost_report into a spreadsheet works today, nothing forces a change this week. Two things argue for moving anyway:
- Per-team and per-identity attribution needs dimensions the legacy cost report does not offer. Its
group_byaccepts onlydescriptionorworkspace_id.3 - The legacy endpoints are not available everywhere. On Claude Platform on AWS the legacy endpoints are unavailable, and on Claude Models on Google Cloud (Anthropic managed) only the legacy usage endpoint is.2
The new API is beta. It requires an anthropic-beta: analytics-usage-cost-2026-08-24 header plus an anthropic-version header on every request, and the SDK and ant CLI send both for you.4 Pin the beta header in your own code and expect fields to move.
Map each old report to the new one
The mapping below is built from the parameter lists of the legacy and new endpoints. Anthropic also publishes its own migration section; it was cut off in the copy I could read, so check the table against it before you cut over.
| Legacy | New | What differs |
|---|---|---|
GET /v1/organizations/usage_report/messages | GET /v1/organizations/analytics/usage | Both give token counts; the new one adds requests and the actor, user profile and product dimensions |
GET /v1/organizations/cost_report | GET /v1/organizations/analytics/cost | Legacy groups only by description or workspace_id; new groups by up to five dimensions |
Fixed daily buckets on cost (bucket_width is 1d) | time_bucket_width of 1m, 1h or 1d, optional | Without a bucket width you get one row per combination for the whole range |
limit counts time buckets (default 7, max 31) | limit counts rows (default 20, max 1000) | Pagination logic changes meaning |
description text such as a model and token label | cost_type and token_type group-bys | Closest replacement in my reading; confirm on live data |
Sources for the table: the legacy usage and cost pages, the legacy cost reference, and the two new reference pages.2356
Three behavioural changes matter more than the renamed paths. First, a dimension is null in group unless you list it in group_by[], and each row is one combination of the grouped dimensions. Second, buckets with no usage or cost produce no rows, so a time series needs zero-filling. Third, the range may span at most 31 days, and starting_at must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.46
That last limit has a practical consequence. Whatever history you want from before 2026 has to come out of the legacy endpoints or your own store before you retire that job. I did not read how far back the legacy endpoints reach, so check it rather than assume.
Credentials and where each endpoint works
Claude Console organizations call the new endpoints with an Admin API key or another Admin API credential, such as an OAuth token with the org:admin scope sent as a bearer token. Claude Enterprise organizations use a key with the read:analytics scope that the primary owner creates in claude.ai.4 The reference pages say the endpoints need an API key with read:analytics or an Admin API key.5
The legacy page is stricter about what fails: workspace API keys don't work against the legacy endpoints.2 The same legacy page lists Admin API key, OAuth with org:admin, or a personal or service account key not scoped to a workspace as valid credentials.
For the collector, Anthropic recommends a dedicated key for the service that collects this data, held in a secrets manager and rotated, with a key expiration set to enforce rotation. Where you can, use a Workload Identity Federation rule with the org:admin scope instead, so the service gets short-lived tokens and no long-lived key sits around.4 That is the cleanest way to reduce what an admin key can do in a reporting job, and it pairs with the guidance in least privilege for provider admin keys.
Platform differences to note:
- Claude Platform on AWS: both endpoints are available, requests use the AWS base URL and IAM actions
ListAccountUsageandListAccountCost, and each request covers only the workspaces in the region of the endpoint you call. You call each region to cover the whole organization.4 - Claude Models on Google Cloud (Anthropic managed): both endpoints are available with Google Cloud credentials and the
usageAnalytics.listandcostAnalytics.listpermissions.4
Fields that can feed per-team attribution
Anthropic has no "team" field on a Messages API request in anything I read. What it gives you are identifiers, and attribution is a join between those and your own org chart. The useful dimensions for a Claude Console organization are these.
workspace_id: the coarsest and most stable. If each team has a workspace, this is already a team report. It is available on the cost endpoint's group-by list.6api_key_id: applies to Claude Console organizations only. Usage with no key, such as requests from the Console or with a Workload Identity Federation token, has a nullapi_key_id.4 Resolve key IDs to names and owners with the List API Keys endpoint, and keep that mapping in a table you version.actorandactor_type: who the request is attributed to: a user, a service account, a federated cloud identity, or the key itself when none of those applies. Personal and service account keys act as their linked identity and show the key inapi_key_id; legacy workspace keys appear as both actor and key; usage that can't be attributed hasactor: null.4user_profile_id: the end-customer dimension. You register a profile per end customer, store theuprof_ID, and send it in theanthropic-user-profile-idheader. Anthropic says profiles don't change billing or pricing on their own.7 On Claude Platform on AWS this dimension is null on every row.4
Two cautions. Managed Agents sessions can be attributed to an Anthropic-managed service account (svac_...) with a null api_key_id, so an agent workload can fall outside a key-based report.4 And a filter on api_key_ids[] matches every request the key authenticated, while actor_ids[]=apikey_... matches only requests attributed to the key itself. Pick one on purpose.4
rbac_group_id exists for teams, but it is a user-group dimension that returns an error when teams aren't available to your organization.4 Don't build a Console API team report on it.
Anything finer than workspace, key, actor and profile (feature, workflow, ticket queue) must come from your side. A gateway that stamps each request can do this; INFRO's attribution docs describe workflow, feature and user_id metadata plus up to five promoted tags such as team, grouped through its own usage endpoint.8 Use Anthropic's report as the control total and your own request records as the breakdown.
Fields that can feed invoice reconciliation
The cost endpoint returns USD, one row per combination of grouped dimensions. group_by takes at most five dimensions, not counting cost_type and token_type. cost_type returns one row per cost component (tokens, web search, code execution, and session_usage for Managed Agents session time), and token_type returns one row per token type.6 That is the grain an invoice line is closest to.
The dimensions that explain why one token costs a different amount from another are the ones to group by when a month does not tie out:
modelservice_tier, with valuesbatch,flex,flex_discount,priority,priority_on_demandandstandardspeed,fastorstandardcontext_window,0-200kor200k-1Minference_geo,global,usornot_available
All five appear as filters and group-bys on the cost endpoint.6 The legacy cost report already carried most of them in its result rows, along with amount as a decimal string and currency.3 Keep amounts as decimals, not floats.
Rules that keep a reconciliation honest:
- Check the total first. Run the cost query with no
group_byand no bucket width for the range; that returns a single row for the whole range.4 Your grouped rows must sum to it. If they don't, you dropped a page or a null-dimension row. - Cut ranges on UTC days and split months. Buckets are UTC, and a range spans at most 31 days.46 Match the boundaries to your invoice period, which I did not verify from Anthropic's side.
- Store
data_refreshed_at. The usage response carries it.4 Re-pull the trailing days instead of assuming a closed day is final. - Treat
order_by=list_amountas a lead, not a fact. The cost endpoint acceptsamount,list_amountortime.6 The part of the reference I read does not definelist_amount, so confirm what it means on the live page before you use it to estimate a negotiated-rate gap.
INFRO's reconciliation compares its own per-request estimates with what the provider's cost API reports per UTC day, and the doc I read names GET /v1/organizations/cost_report for Anthropic.9 That is the legacy endpoint, which Anthropic still supports. I did not read any statement from INFRO about moving to the new one, so ask before assuming which endpoint a given tool reads.
A rebuild sketch
This pulls daily cost grouped by workspace and model with the price-changing dimensions, pages through every row, and stores the raw payload. It does not assume the field names inside each row's cost object, which the pages I read did not spell out.
import os, json, requests
BASE = "https://api.anthropic.com/v1/organizations/analytics/cost"
HEADERS = {
"x-api-key": os.environ["ANTHROPIC_ADMIN_KEY"],
"anthropic-version": "2026-10-21",
"anthropic-beta": "analytics-usage-cost-2026-08-24",
"User-Agent": "FinopsPull/1.0 (https://example.com)",
}
def pull(start, end):
params = {
"starting_at": start, # e.g. 2026-10-01T00:00:00Z
"ending_at": end, # exclusive, at most 31 days later
"time_bucket_width": "1d",
"order_by": "time",
"order": "asc",
"limit": 1000,
"group_by[]": ["workspace_id", "model", "service_tier",
"speed", "context_window"],
}
rows = []
while True:
r = requests.get(BASE, headers=HEADERS, params=params, timeout=60)
r.raise_for_status()
body = r.json()
rows.extend(body["data"])
if not body.get("has_more"):
return rows, body.get("data_refreshed_at")
params["page"] = body["next_page"]
rows, refreshed = pull("2026-10-01T00:00:00Z", "2026-11-01T00:00:00Z")
with open("claude_cost_2026_10.jsonl", "w") as f:
for row in rows:
f.write(json.dumps(row) + "\n")
print(len(rows), "rows; data_refreshed_at:", refreshed)Whether the cost response carries data_refreshed_at the way the usage example does is something to confirm; the code uses .get. Run the same range with no group_by and compare totals before trusting the grouped file.
Failure modes to test before you cut over
- Silent nulls. A dimension you did not group by is null, and a dimension that does not apply to your organization is null on every row with a filter that matches nothing.4 A team report filtered by
api_key_ids[]on an organization where keys do not apply returns nothing, not an error. - Missing days. Empty buckets produce no rows. A chart that skips them draws a false trend.4
- Cardinality. Five group-bys across model, tier, speed, context window and workspace can return many rows.
limithas a maximum of 1000, and every combination is returned across pages, not a capped top set.6 Follownext_pageuntilhas_moreis false. - Deleted users.
exclude_deleted_usersdrops rows whose actor is a deleted user, but it requiresgroup_by[]=actor, and a page may then hold fewer thanlimitrows.6 Leave it off in a reconciliation job, or the total will not tie. - Beta drift. The header name carries a date,
analytics-usage-cost-2026-08-24, and the release note calls the API a beta.1 Run the old and new jobs in parallel for at least one full invoice cycle and diff the totals before turning the legacy job off.
Where a gateway helps, and where it does not
Anthropic's report is the provider's record of what it will bill. A gateway keeps its own record of each request, which is what lets you break a workspace total down by feature or customer. INFRO records estimated provider cost per request and can group it by project, key, model or attributed metadata, and its daily reconciliation compares that estimate with Anthropic's reported cost using a separate admin credential.98 It is a cross-check, not a replacement for Anthropic's numbers. Request-level estimates cannot see traffic that never passed through the gateway, so keep Anthropic's workspace and key totals as the control and compare the two. The reconciliation article covers that comparison in more depth.
