Claude Usage and Cost Analytics API: what to migrate, what to keep

Anthropic's Usage and Cost Analytics API, in beta since 29 October 2026, reports Claude token usage and cost by model, workspace, API key and the identity behind each request. It suits finance reports and spend attribution, but its data refreshes in hours, not minutes, so keep near-real-time budget alerts on the legacy Usage and Cost API for now.

What Anthropic released

The Usage and Cost Analytics API was announced by Anthropic on 29 October 2026 in the Claude API release notes. It is in beta and needs the anthropic-beta: analytics-usage-cost-2026-08-24 header on every request, alongside the usual anthropic-version header. The official SDKs and the ant CLI send both headers and page through results for you.

It has two endpoints, documented in the Usage and Cost Analytics API guide:

• GET /v1/organizations/analytics/usage returns token counts and request counts.
• GET /v1/organizations/analytics/cost returns cost in US dollars, as decimal strings in cents with six decimal places.

The same endpoints serve Claude Console organizations, which call them with an Admin API key or an OAuth token with the org:admin scope, and Claude Enterprise organizations, which use a key with the read:analytics scope. They are also available on Claude Platform on AWS, authorised through IAM, and on Claude Models on Google Cloud (Anthropic managed), authorised through Google Cloud IAM permissions.

At the same time, Anthropic made the older Usage and Cost API a legacy API, along with the four usage and cost report endpoints of the Claude Enterprise Analytics API. The release notes say all of them remain supported, and no retirement date has been published.

What the new API does differently

The biggest change is the shape of the results. Instead of a list of time buckets, each response is a list of rows. Each row covers one combination of the dimensions you group by, with the dimensions in a group object and the metrics in usage or cost. Rows are ranked by a metric of your choice, so "which API keys cost the most this month" is a single request.

The details that matter in practice, all from the official guide:

• Grouping: up to five dimensions per request, such as model, workspace_id, api_key_id, service_tier, inference_geo and actor. The cost endpoint adds cost_type and token_type, which don't count towards the five.
• Actors: the actor dimension says who a request is attributed to, whether a user, a service account, a federated AWS or Google Cloud identity, or the API key itself when no identity is linked. Claude Code usage after a sign-in without an API key is attributed to the member who signed in.
• Filters: most dimensions have a list filter such as models[], taking up to 100 values. An unknown model name or workspace ID now matches nothing instead of returning an error.
• Time buckets: optional, at one minute, one hour or one day. Without them you get one total per combination for the whole range.
• Date range: starting on or after 1 January 2026, within the past year, and at most a 31-day span per request, as the date range rules set out. Per-minute buckets cover at most 24 hours per request.
• Cost fields: amount is the cost after discounts and before credits, and the new list_amount is the cost at list prices. Requests and code execution usage now appear too.

The trade-off: freshness

The migration table is explicit. Legacy Usage and Cost API data typically appears within 5 minutes. The new API typically refreshes within 4 hours and can take up to 24 hours. Every response carries a data_refreshed_at timestamp, and values can still be revised until about a week after the end of the calendar month as reconciliation runs, according to the data freshness section.

That decides most of the migration plan. Our advice for Claude Console teams:

• Move now: monthly finance reports, chargeback by workspace or team, per-key and per-identity attribution, and dashboards that answer "who spent what". These gain the most from ranked rows, actor grouping and list_amount.
• Keep on the legacy API for now: alerts meant to catch a runaway agent or a leaked key within minutes. A report that can lag by hours will not stop that spend in time, so pair it with spend limits and the controls in our guide to controlling AI agent running costs.
• Close the books on settled data: for final monthly totals, query only months that ended long enough ago for revisions to finish, and record the data_refreshed_at value you reported against.

For Claude Enterprise organisations, the case to move is stronger. The legacy reports return only the top 100 groups in each bucket, while the new endpoints return every combination with data, and the Enterprise migration section says your key, the date limits and the organisation-level rate limit carry over.

What breaks when you port a job

Most names carry over, but a straight copy of a legacy query will give wrong or missing numbers. Check these before you switch a report:

1. Bucket width: the legacy bucket_width defaulted to daily buckets. The new time_bucket_width has no default, so leaving it out returns totals for the whole range rather than daily rows. ending_at is required when you set it.
2. Empty buckets: days with no usage no longer appear. Fill the gaps with zeros before you chart or compare them.
3. Pagination: limit now counts rows (1 to 1,000), not buckets. The number of pages depends on how many combinations have data.
4. Long ranges: split anything longer than the per-request span into several requests.
5. Identities: account_ids[] and service_account_ids[] become actor_ids[], and grouping by account becomes group_by[]=actor.
6. Default workspace: it now has its real workspace ID instead of null, so any code that treats null as "default" needs changing.
7. Silent filters: a misspelled model name returns no rows rather than an error. Add a check that alerts when a filtered report comes back empty.
8. Cost descriptions: group_by[]=description is gone. Group by model, cost_type and token_type instead.

Run the old and new reports side by side for a closed month and reconcile them before you retire the legacy job. Because the API is in beta, pin the beta header in one place in your code so a future header change is a one-line edit. If you already export Claude telemetry, the OpenTelemetry export covers request-level traces, while this API covers billing-grade totals.

Governance: treat the reporting key as sensitive

An Admin API key can do far more than read reports. Anthropic's guide recommends giving the collection service its own key, storing it in a secrets manager, setting a key expiration so it rotates, and preferring a Workload Identity Federation rule with the org:admin scope where possible, so the service uses short-lived tokens. On Claude Platform on AWS, each request covers only the workspaces in that AWS region, so a complete report means calling each region's endpoint.

Frequently asked questions

Do I have to migrate from the Claude Usage and Cost API now?

No. Anthropic made the Usage and Cost API a legacy API on 29 October 2026 but says it remains supported, and no retirement date has been published. The new Usage and Cost Analytics API is in beta. Move reporting and attribution jobs when the new grouping helps, and keep alerts that need data within minutes on the legacy endpoints until freshness changes.

How fresh is the data in the Usage and Cost Analytics API?

Anthropic's guide says data typically refreshes within 4 hours and can take up to 24 hours, compared with about 5 minutes on the legacy API. Each response includes a data_refreshed_at timestamp showing what has been loaded. Values can also be revised after the month ends while reconciliation runs, so final monthly totals should come from settled months.

Can I see Claude spend per person or per service account?

Yes. Group by the actor dimension to attribute usage and cost to a user, a service account, a federated cloud identity, or the API key itself when no identity is linked. Anthropic's guide also gives a query for per-user Claude Code cost, using the products filter set to claude_code with grouping by actor on the cost endpoint.

What key does the Usage and Cost Analytics API need?

Claude Console organisations use an Admin API key or an OAuth token with the org:admin scope. Claude Enterprise organisations use a key with the read:analytics scope, created by the primary owner. Because an Admin API key carries wide permissions, give the reporting service its own key with an expiry, or use Workload Identity Federation for short-lived tokens.