Claude Usage and Cost API Is Legacy: Migrate to Analytics and Compare Totals

What the October 29 release note changes

Anthropic's release note for October 29, 2026 launches the Usage and Cost Analytics API in beta with the analytics-usage-cost-2026-08-24 beta header. Its two endpoints, /v1/organizations/analytics/usage and /v1/organizations/analytics/cost, report token usage and cost for Claude Console and Claude Enterprise organizations, filtered and grouped by dimensions such as model, workspace, API key and the user or service account behind each request.

The same note makes the Usage and Cost API a legacy API, together with the usage_report, cost_report, user_usage_report and user_cost_report endpoints of the Claude Enterprise Analytics API. All of them remain supported, and the note gives no shutdown date. Nothing breaks today. The practical question is when you move a dashboard, and how you prove the new numbers before you do. If you are new to the platform itself, start with our Claude API guide; this report covers only the reporting change.

What carries over for Console integrations

The migration section of the new guide addresses Claude Console organizations that call /v1/organizations/usage_report/messages and /v1/organizations/cost_report. Your Admin API key, the anthropic-version header, starting_at and ending_at, the bucket values 1m, 1h and 1d, bracket notation, pagination field names and the token and cost field names all carry over. The changes that touch dashboard code:

The table is a selection; the guide lists further rows, including cost amounts. Two of these rows fail silently. An unknown workspace or API key ID used to raise an error; now it matches nothing, and so does a misspelled model name, so a chart can drop to zero without any exception. And a chart keyed on workspace_id == null for the default workspace will lose that series. Anthropic's guide says the default workspace returns "name": "Default" from Get Workspace, which gives you a lookup to replace the null check.

The same daily report, before and after

To reproduce the legacy daily report, the guide says to request time_bucket_width=1d with the same group_by[], page through with limit=1000, group rows by starting_at and fill missing days with zeros. Its own example for daily usage by model over one week, before:

curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

and after:

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
time_bucket_width=1d&\
limit=1000" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

Add order_by=time&order=asc if your chart expects the days in order. The guide adds that the SDK and the ant CLI send both headers for you. The new rows are ranked by total_tokens by default, according to the usage endpoint reference, and empty days no longer arrive as zero buckets.

Where totals drift

Some differences are documented, so a mismatch is not automatically a bug. The guide lists these:

• Code execution. The legacy usage report did not include it. The new usage endpoint returns it as rows with model: null, and adds requests and total_tokens.
• Freshness. Legacy data typically appears within 5 minutes. New data typically refreshes within 4 hours and can take up to 24 hours. Every response carries data_refreshed_at; usage after it is missing or partial.
• Revisions. Values can change as late events arrive, until about 7 days after the end of the calendar month. For final totals, the guide says to query only months that ended at least 7 days ago.
• Null instead of defaults. Usage with no geo or tier now has null where the legacy report showed inference_geo: "not_available" and service_tier: "standard".
• Priority Tier. The legacy page says Priority Tier costs are not in its cost endpoint. The new cost endpoint shows those requests with zero token cost, but web search on them is billed at the standard rate.

Cost amounts change format too. The cost endpoint reference describes amount as post-discount, pre-credit, in fractional cents, next to a new list_amount at list price. The guide's example "41280.000000" is $412.80. Compare amounts as numbers, not strings: the legacy "123.45" becomes "123.450000".

Run one closed day through both APIs

This is a proposed acceptance check, not a test we ran. Pick a September 2026 day: September ended more than 7 days ago, so its values should be final, and it falls within the 365-day window. Request that single day from both endpoints with group_by[]=model, a one-day bucket and, on the new endpoint, limit=1000, then flatten each response to one line per model with the token fields that carry over:

# legacy: buckets with a results list
jq -r '.data[] | .results[] | [.model, .uncached_input_tokens, .cache_read_input_tokens, .output_tokens] | @tsv' legacy.json

# new: rows with group and usage
jq -r '.data[] | [.group.model, .usage.uncached_input_tokens, .usage.cache_read_input_tokens, .usage.output_tokens] | @tsv' analytics.json

The field paths come from the legacy usage report reference and the new usage reference; the jq lines themselves are ours. Compare the two outputs by model and set the null model row aside as code execution before you judge the match. Do the same for cache_creation.ephemeral_5m_input_tokens and ephemeral_1h_input_tokens. On the cost side, group the new endpoint by model and the legacy report by description, which the legacy page says returns parsed fields such as model, and compare numerically, keeping Priority Tier traffic separate.

Record every remaining gap with its model and field. When the per-model numbers line up, switch the dashboard and keep the legacy call running beside it for one billing cycle. The AI cost modeling guide covers what to do with those numbers once they are trusted.

Limits to plan for

The new API is stricter about ranges. starting_at must be on or after January 1, 2026 and within the last 365 days, one request covers at most 31 days, ending_at is required with a time bucket, and 1m buckets cover at most 24 hours. A backfill that asked the legacy API for a quarter now needs at least three requests. Pagination cursors can also expire after a data refresh; the cost reference says the request then returns HTTP 410 and pagination must restart from the first page.

Claude Enterprise organizations follow a separate section of the guide. The per-user reports map to group_by[]=actor&actor_types[]=user_actor, the old cap of the top 100 groups per bucket goes away, and Claude Tag usage changes from product: "claude-tag" to "claude_tag". A string match on the old product value will stop counting that usage.