When you build the Claude API into multiple internal systems or into per-customer services, you end up needing to report at month end "which department, which customer and which API key used how much." If you copy figures from the admin screen by hand, it is hard to keep a basis for the allocation, and you are also slow to notice overuse.
On October 29, 2026, Anthropic released the "Usage and Cost Analytics API" for this kind of aggregation in beta. At the same time, the existing "Usage and Cost API" and the usage and cost reports in the Claude Enterprise Analytics API (usage_report, cost_report, user_usage_report, user_cost_report) became legacy. All of them remain available. Based on the official documentation, this article sets out what the new API can aggregate and what to check before migrating an existing aggregation setup.
What the new API can aggregate
There are two endpoints.
GET /v1/organizations/analytics/usage: token counts and request countsGET /v1/organizations/analytics/cost: cost in US dollars
During the beta, every request requires the anthropic-beta: analytics-usage-cost-2026-08-24 and anthropic-version headers. The SDKs and the ant CLI add both automatically, and also fetch the remaining pages when reading through them.
As use cases, the documentation lists breakdowns of cost and usage by workspace, API key, model, service tier and requesting identity, sorting by highest usage, and time series by day, hour and minute. The same endpoints and parameters work for both Claude Console and Claude Enterprise organizations. However, some dimensions, such as api_key_id, exist only for Claude Console organizations, and others, such as slack_channel_id, exist only for Claude Enterprise organizations. A dimension that does not apply to your organization is basically null on every row, and filtering on it matches nothing.
You can specify up to five aggregation dimensions with group_by[] (cost_type and token_type, which exist only on the cost endpoint, do not count toward this number). Most dimensions have a corresponding filter (for example, models[]=claude-opus-5-5), and you can pass up to 100 values to a single filter. Multiple values in the same filter are joined with OR, and different filters are joined with AND.
"Who used it" is represented by a dimension called actor. It is a user, a service account, a federated identity from AWS or Google Cloud, or, if it is none of those, the API key itself. Personal keys and service account keys are recorded as the person or account they are tied to, but older workspace keys are not tied to anyone, so the key itself becomes the actor. Usage not tied to any identity is actor: null.
Before using it for budget alerts: reporting delays and month-end finalization
The most important thing to check before building it in is how quickly data is reflected.
- Data in the new API is usually reflected within 4 hours of use, and can take up to 24 hours at the slowest
- The existing Usage and Cost API was described as usually reflecting data within 5 minutes
- Values can change until about 7 days after the end of the calendar month because of late-arriving records and reconciliation. In the documentation's example, values for October 1 can change until around November 7
Every response includes data_refreshed_at, and usage after this time is missing or only partial. If you want the same results from repeated calls, the documentation recommends setting ending_at to a point no later than a data_refreshed_at you have already seen, and if you need finalized totals, aggregating only months that ended at least 7 days ago.
From here on is the editorial team's own summary. If you have built a mechanism that calls the existing API every few minutes and stops things when usage runs too high, replacing it with the new API could delay detection by up to a day. It is safer to design separately for knowing that you are nearing your budget cap and for allocating monthly billing to departments or customers. For the former, rather than relying only on the new API, also consider counting the records of requests sent on your own system's side. For the latter, finalize at least 7 days after the end of the month.
Getting the currency units right
cost on the cost endpoint contains the following values.
amount: cost after discounts and before credits are appliedlist_amount: cost at list pricecurrency: always"USD"
Amounts are strings in cents with six decimal places; in the documentation's example, "41280.000000" is $412.80. Being in cents is the same as in the existing cost report, and what changes is the number of decimal places. The migration table says that a value like "123.45" takes the form "123.450000", and that list_amount is added. In both cases, if you convert the string directly to a number and treat it as dollars, the amount will be 100 times too large, so divide by 100 when converting to dollars.
When reconciling with invoice amounts, note that these are values before credits are applied. Requests processed within a Priority Tier commitment are aggregated with a token cost of 0, and commitment fees are not included in this data. How monthly API credits are handled is covered in our article on Claude Team API credits.
What changes when migrating from the existing API
From the documentation's migration section, here are the differences most likely to affect existing aggregation code.
| Item | Existing Usage and Cost API | New API |
|---|---|---|
| Time buckets | bucket_width, default 1d | time_bucket_width, no default. If not specified, you get the total for the whole period. When specified, ending_at is required |
| Page size | limit is the number of time buckets | limit is the number of rows (1 to 1,000, default 20) |
| Period | Any period | On or after January 1, 2026 and within the last 365 days, up to 31 days per request. Up to 24 hours for 1m buckets |
| Specifying an ID that does not exist | Error | Matches nothing (the same goes for misspelled model names) |
| Default workspace | workspace_id: null | The actual wrkspc_ ID |
The fact that a nonexistent ID produces an empty result rather than an error is a change that is easy to miss. If you pass a misspelled models[], usage will look like 0. If aggregated results suddenly drop to 0, check your filter values first.
To produce the same shape as the existing daily report, the guidance is to specify time_bucket_width=1d and the same group_by[], page through with limit=1000, group by starting_at, and fill days with no usage with 0. This is because the new API does not return rows for combinations with no usage.
The table so far covers migration from the Usage and Cost API used by Claude Console organizations. If you are migrating from Claude Enterprise reports (such as usage_report), the documentation has a separate section. Keys, period limits and amount fields carry over, and the limit of the top 100 groups per time bucket goes away, while the handling of ending_at, the name of user_ids[] and other things change.
Handling keys
Claude Console organizations use an Admin API key (or other Admin API credentials, such as an OAuth token with the org:admin scope), and Claude Enterprise organizations use a key with the read:analytics scope that the Primary Owner creates on claude.ai after enabling the Analytics API.
When calling with an Admin API key, the documentation asks you to prepare a key dedicated to the aggregation service, store it in a secrets management system and rotate it regularly. Where possible, it recommends using short-lived tokens through Workload Identity Federation and not holding long-lived keys.
Both endpoints are also available on Claude Platform on AWS and Claude Models on Google Cloud (Anthropic managed), and you call them with each cloud's authentication and permissions. On AWS, only workspaces in the region you call are covered, and user_profile_id and the Claude Managed Agents dimensions are null on every row. The existing API is not available on AWS, and only the usage endpoint is available on Google Cloud.
What to decide before migrating
The new API is in beta. The documentation directs new integrations to use the new API, but the existing API continues to be supported as "legacy," and as of November 6, 2026, no end date has been given. For aggregation that is already running, the editorial team recommends proceeding in the following order rather than rushing to switch.
- Check whether your current aggregation relies on data being reflected "within a few minutes." If it does, prepare another method for that part
- Check that your amount conversion code can read strings with six decimal places and that it converts cents to dollars. Also reflect the fact that the values are before credits are applied in your reconciliation with invoices
- For the same month, compare the results from the existing API and the new API side by side, and if there are differences, check whether they can be explained by the differences in the table above (default workspace, nonexistent IDs, days with no usage)
If you run separate API keys for each customer, please also see our article on user profiles.
Scope of verification
On October 31 and November 6, 2026, we directly opened and checked the Claude Platform release notes (the October 29, 2026 entry and subsequent entries through November 5) and the documentation "Usage and Cost Analytics API" and "Usage and Cost API" on platform.claude.com (document research). We did not make actual calls with an Admin API key, and we have not verified the response contents, the actual speed of reflection, or numerical differences from the existing API. The idea of separating budget monitoring from allocation and the approach to migration are the editorial team's proposals.
For aggregating usage of systems with built-in AI, or for building a way to allocate costs to departments and customers, please contact us through consultation on development, AI, and automation.
