Claude's Usage and Cost Analytics API: per-person spend, a few hours late
Anthropic's new beta analytics API breaks Claude usage and cost down by user, key and model. What it reports, how fresh it is, and how to use it safely.
On 29 October 2026, Anthropic launched the Usage and Cost Analytics API in beta. It answers a question finance and platform teams have been asking since AI coding tools spread through engineering: who, or what, is spending the money? The new endpoints break token usage and cost down by model, workspace, API key and the person or service account behind each request, for both Claude Console and Claude Enterprise organisations. They also come with a trade-off worth understanding before you build a dashboard on them: the data is hours old, not minutes.
What was released
The release notes for 29 October list two endpoints, /v1/organizations/analytics/usage and /v1/organizations/analytics/cost, behind the beta header analytics-usage-cost-2026-08-24. On the same day, the older Usage and Cost API became a legacy API, along with the usage and cost report endpoints of the Claude Enterprise Analytics API. Anthropic says all of them remain supported, and the new documentation includes migration guides.
Because the new API is in beta, its parameters and fields can still change. Pin the header version you tested against and expect to revisit the integration.
What it reports
The API documentation describes a query model built around dimensions:
- Grouping.
group_by[]takes up to five dimensions, such as model, workspace, API key or actor. Each row is one combination of the dimensions you chose. - Actors. The
actordimension is who a request is attributed to: a user, a service account, a federated cloud identity, or, when none of those is behind it, the API key itself. Personal and service account keys show the linked identity as the actor. Legacy workspace keys show up as their own actor. - Filters. Most dimensions have a matching filter, up to 100 values each.
- Time buckets. Results can be split into one-minute, one-hour or one-day buckets.
- Cost detail. The cost endpoint adds two dimensions of its own,
cost_typeandtoken_type. Each row carriesamount, which is the cost after discounts and before credits, andlist_amount, the cost at list prices. Both are strings in cents with six decimal places, so"41280.000000"means $412.80.
For coding tools, the documentation gives a direct recipe: call the cost endpoint with products[]=claude_code&group_by[]=actor to get Claude Code cost per person.
The limits that shape how you use it
Four details in the documentation matter more than the feature list.
Freshness. The documentation says data "typically refreshes within 4 hours of the underlying usage and can take up to 24 hours". The legacy API's data typically appeared within five minutes. Every response carries a data_refreshed_at timestamp, and usage after it is missing or partial. This is a reporting tool, not a live spend meter.
Revisions. Values can be revised until about seven days after the end of the calendar month. October's figures can change until about 7 November. For final monthly totals, the documentation suggests querying only months that ended at least seven days ago.
Ranges. starting_at must be on or after 1 January 2026 and within the last 365 days. One request covers at most 31 days, and one-minute buckets at most 24 hours. Longer reports need several requests.
Commitments. Requests served under a Priority Tier commitment appear with zero token cost, because the commitment fee is billed separately and is not in this data. If you have a commitment, the API will understate your total bill unless you add the fee yourself.
Handling the credential
For Claude Console organisations, the endpoints need an Admin API key or another admin credential. That is a powerful key to hand to a reporting job. The documentation recommends giving the collecting service its own key, storing it in a secrets manager, rotating it with a key expiration, or better, using a Workload Identity Federation rule with the org:admin scope so the service gets short-lived tokens. Claude Enterprise organisations use a key with the read:analytics scope instead.
What it means for engineering and security leaders
- Attribution gets easier, but only with named identities. Per-person reporting depends on requests being tied to a user or service account. Shared workspace keys collapse many people into one actor. Moving teams to personal and service account keys is what makes the new
actordimension useful. - Reporting and enforcement are different jobs. An API that is four to 24 hours behind can tell you who overspent yesterday. It cannot stop a runaway agent loop this afternoon. Limits that act in real time have to sit closer to the calls, such as provider spend limits or a proxy.
- Month-end numbers move. Finance teams reconciling invoices should wait for the revision window to close, or label early figures as provisional.
- It covers one provider. Teams that also use other model providers still need a way to combine costs across them. Compare like with like:
amounthere is after discounts and before credits.
Practical takeaways
- Start with one weekly report: cost by actor and model for the last seven complete days, filtered to Claude Code. That alone answers most "who is spending what" questions.
- Check how many requests come back attributed to an API key rather than a person. Those are your attribution gaps.
- Treat figures newer than
data_refreshed_atas incomplete, and month-end totals as provisional until about the seventh of the following month. - Give the reporting job its own short-lived credential, not a copy of an administrator's key.
- If you rely on Priority Tier, add the commitment fee to any total the API gives you.
For background on why the same work can cost very different amounts, see the harness sets the bill and prompt caching as a cost control.
If your tools' API-key calls go through SpanDock's model proxy, every call is recorded with the model that answered, its tokens and its cost, and per-person budgets are checked as each call is made rather than hours later. Near the limit, only cheaper models are used; over it, calls are blocked, moved to the cheapest model or flagged, as the administrator chooses. Only API-key traffic is routed, not Claude Pro or Max sign-ins. The model proxy is on every plan; per-person budgets are on the Standard plan and up.