Claude Usage and Cost Analytics API: What Changes for You

Anthropic's platform release notes for October 29, 2026 record two things. The Usage and Cost Analytics API launched in beta, with two endpoints that report token usage and cost for Claude Console and Claude Enterprise organisations, filterable and groupable by model, workspace, API key and the user or service account behind each request. And the older Usage and Cost API, together with the Enterprise Analytics API's usage and cost report endpoints, became legacy. The notes add that all of them remain supported, and no removal date is given.

For most readers the practical question is whether anything breaks. Today, nothing does. The reason to act is that the new API is where Anthropic is building, it is the only one that serves Console and Enterprise organisations from the same integration, and its response shape, date limits and freshness guarantee are different enough that a dashboard written against the legacy report will not port by renaming a path. This post works through those differences from the documentation pages as retrieved on November 5, 2026, and ends with a plan. How Claude spend fits with the other vendors' controls is covered in our comparison of AI spend controls and usage caps.

The release notes entry is two bullet points. The first announces the launch: "We've launched the Usage and Cost Analytics API in beta with the analytics-usage-cost-2026-08-24 beta header", naming the two endpoint paths and the dimensions you can filter and group by. The second reclassifies the old surface: the Usage and Cost API is now a legacy API, and so are the four report endpoints of the Claude Enterprise Analytics API, and "All of them remain supported." The notes link to two migration sections, one for each legacy API, which are the basis of sections 06 and 07 below.

The documentation page for the new API describes what it is for in four verbs: attribute spend across workspace, key, model, service tier or identity; find top consumers by ranking on tokens, requests or cost; build time series in daily, hourly or per-minute buckets; and integrate once, because the same endpoints, parameters and response fields serve Console and Enterprise organisations. The last of those is the structural change. Previously a company that used both the Claude Platform and Claude Enterprise needed two integrations with two key types and two response formats. Now it needs one integration with two keys.

One naming trap is worth clearing at the start. The beta header carries the date 2026-08-24, which is the version of the beta contract, not the launch date; the API launched on October 29. And the word in the release note is legacy, not deprecated. Anthropic uses deprecated for things with a removal date, as it did the next day for fast mode on Opus 4.8, which we cover in a separate post. A legacy API has no such date, and nothing in these pages implies one.

The usage endpoint returns token counts by type and request counts. Its ranking metric, set with order_by, is total_tokens by default and can be output_tokens, uncached_input_tokens, requests or time. The cost endpoint accepts the same filters, dimensions and time buckets and returns a cost object per row holding amount, the cost after discounts and before any credits are applied; list_amount, the cost at list prices; currency, which is always USD; and requests. Amounts are decimal strings in cents with six decimal places, so the documentation's example of "41280.000000" is $412.80. Two dimensions exist only on the cost endpoint and do not count toward the five-dimension limit: cost_type and token_type, which split each row by the kind of charge and the kind of token.

The quick-start request in Anthropic's documentation is the shape every integration starts from: a date range, a bucket width, a group_by and a page size, with the beta header and the version header on every call. The SDK and the ant command-line tool add both headers and fetch the remaining pages as you read, so limit only sets the page size there.

That request, copied from Anthropic's quick start, returns one row per model per day for the first week of September. Replace the path with /analytics/cost and add group_by[]=cost_type and group_by[]=token_type to see the same week as a bill. The failure case to design against is the one the documentation flags for the cost endpoint: because cost_type and token_type do not count toward limit, a page can hold more rows than limit, so a client that allocates by page size will be surprised.

Authentication depends on the organisation type, and the key types are not interchangeable. A Claude Console organisation uses an Admin API key or another Admin API credential such as an OAuth token with the org:admin scope, sent as a bearer token rather than in the x-api-key header. A Claude Enterprise organisation uses an Analytics API key with the read:analytics scope, created in claude.ai by the primary owner after the Analytics API has been enabled for the organisation. Anthropic's analytics overview page states the general rule that an Admin API key cannot call the Enterprise Analytics API and an Analytics API key cannot call the Admin API, and names this new API as the one exception: Enterprise organisations call it with their Analytics API key.

Two further access notes matter for larger deployments. The Admin API is unavailable for individual accounts, so a solo developer on a personal account cannot use this API at all until an organisation exists. And organisations that reach Claude through a cloud platform have their own paths: on the Claude Platform on AWS, the endpoints are authorised through IAM actions and each request covers only the workspaces in the region of the endpoint called; on Claude Models on Google Cloud under Anthropic management, the usage endpoint needs the usageAnalytics.list permission and the cost endpoint needs costAnalytics.list. The documentation also recommends that a service collecting this data get its own Admin key with an expiry, or better a Workload Identity Federation rule, so there is no long-lived secret to leak.

This is where a port stops being a path rename. In the legacy API, data was a list of time buckets, oldest first and including empty ones, each holding a results list in which dimensions and metrics sat side by side. In the new API every row has three parts: starting_at and ending_at give the period the row covers, group holds every dimension, and usage or cost holds the metrics. A dimension is null unless you listed it in group_by, and group_by takes up to five dimensions. Every combination of grouped dimensions that has usage or cost appears exactly once across the pages of a query, and combinations with nothing produce no row.

Ordering changed too. Rows come back ranked by the order_by metric across the whole range, largest first by default. A time series is opt-in: set time_bucket_width to 1m, 1h or 1d and order_by to time, and rows arrive one bucket after another, newest bucket first unless you pass order=asc, with the largest rows first within each bucket. Buckets with no usage produce no rows, so Anthropic's own instruction is to fill empty buckets with zeros on the client. Filters work alongside grouping: most dimensions have a matching list filter in bracket notation, repeated values within a filter combine with OR, different filters combine with AND, and you can filter by a dimension without grouping by it.

The dimension that most changes attribution is actor. It is who a request is attributed to: a user, a service account, a federated cloud identity, or, when none of those is behind the request, the API key itself. Personal and service-account keys act as the identity they are linked to, so their requests show that identity as the actor and the key in api_key_id; legacy workspace keys appear as both. Requests made without a key, from the Console or with a federated token, have a null api_key_id. The two filters answer different questions: api_key_ids matches every request a key authenticated, whoever it is attributed to; actor_ids with a key ID matches only requests attributed to the key itself. A finance dashboard that previously summed by key will double-count or under-count if it conflates the two.

The one change that can break an operational use rather than a reporting one is freshness. Anthropic's migration table puts the two side by side: on the legacy API, data typically appeared within five minutes; on the new API, data typically refreshes within four hours and can take up to 24 hours. Values can then be revised as late events arrive and reconciliation runs, until about seven days after the end of the calendar month. The documentation's example is that values for October 1 can change until about November 7, and its advice for invoicing-grade totals is to query only months that ended at least seven days ago.

Every response carries a data_refreshed_at timestamp, and usage after that time is missing or partial. For stable results across repeated calls, set ending_at at or before a data_refreshed_at you have already seen; every page of a paginated query reads the same snapshot, so the timestamp is identical across pages. The failure case is a spend-cap job that polled the legacy report every ten minutes and cut off keys on a threshold. On the new API that job is reading data up to a day old and will fire late; a cap that must act within minutes belongs in a gateway or proxy in front of the API, not in a reporting endpoint. Our comparison of subscriptions and usage credits covers where the vendor-side limits sit.

Anthropic's migration section for Console organisations lists what carries over: the Admin API key, the anthropic-version header, starting_at and ending_at, the bucket width values, bracket notation, the pagination field names, and the token and cost field names. Then it tabulates what changes. The beta header is new on every request. bucket_width becomes time_bucket_width and has no default, so an integration that relied on daily rows must now pass 1d explicitly and will get whole-range totals if it does not. limit counts rows instead of buckets. The account and service-account filters become actor_ids with the same tagged IDs, and group_by moves to actor or actor_type. context_window becomes context_windows.

Several silent changes are the ones to test for. The cost report's free-text description grouping is gone, replaced by structured dimensions: model, cost_type, token_type, context_window, service_tier, inference_geo and speed, all of which fit in one request. The default workspace, previously null, now has its own real workspace ID. Usage with no inference geography or service tier is now null in both fields rather than the strings not_available and standard, though the not_available filter value still matches those rows. Cost service_tier now reports the actual tier rather than only standard or batch, and amounts gain six decimal places and a list_amount companion. Code execution, previously absent from the usage report, now appears as usage rows with a null model, and request counts exist on both endpoints.

To reproduce the legacy daily report, the documentation's recipe is to request time_bucket_width=1d with the same group_by, page through with limit=1000, group rows by starting_at, fill missing days with zeros, and add order_by=time and order=asc to get the days in order. That is a client-side change, and it is the whole of the port for a team that only needs the old daily table back.

For Claude Enterprise organisations the legacy surface is the four report endpoints under /v1/organizations/analytics: usage_report, cost_report, user_usage_report and user_cost_report. Anthropic's migration section says these remain supported, and then gives four reasons to move: every group in every time bucket rather than the top 100 groups per bucket; grouping by actor or actor_type together with other dimensions on both usage and cost; rows ranked by a metric of your choice or ordered by time bucket; and one integration that also serves Console organisations. The top-100 ceiling is the one most likely to have been silently truncating a large organisation's per-user report.

What carries over is longer than for Console: the key, the earliest date, the 365-day lookback and 31-day span, the filter and dimension names and values with two exceptions, the user actor fields, the metric and amount fields, data_refreshed_at, the cursor rules, and the organisation-level rate limit of 60 requests per minute. The only new header is the beta header. The changes are mostly renames: bucket_width becomes time_bucket_width, ending_at becomes required with a bucket width, minute buckets shrink from 31 days to 24 hours per request, user_ids becomes actor_ids with the same tagged user IDs, and the Claude Tag product value changes from claude-tag with a hyphen to claude_tag with an underscore, with the filter accepting either spelling.

The per-user reports have the one behavioural change to test. Where user_usage_report and user_cost_report returned one row per user, the replacement is group_by[]=actor with actor_types[]=user_actor. Without that filter the result also includes rows for non-user identities and a row with a null actor for unattributed usage. And exclude_deleted_users now requires group_by[]=actor, returns a 400 without it, and drops only rows whose actor is a user marked deleted; rows for other identities and the null-actor row stay. A report that compared the old per-user total with a sum of the new rows will not match unless the filter is applied.

Because nothing is being removed, the migration can be run side by side: keep the legacy job, add the new one, compare for a month that has closed, and then retire the old job. The routing below sorts the common situations by what they actually need from the API.

Two housekeeping steps close the sprint. Give the collector its own credential with an expiry or a federation rule, as the documentation recommends, rather than reusing a human's Admin key. And because the API is in beta and its schema may change, pin the SDK version and read the release notes before each upgrade. If you want help building the attribution model itself, so that every Claude request lands on a team and a product, it is part of what our AI transformation engagements cover.