Claude’s new cost analytics API trades speed for richer reporting
Anthropic launched its Usage and Cost Analytics API beta on October 29, giving Claude Console and Enterprise organizations shared endpoints for analyzing consumption and spending. The release notes say the older reporting APIs remain supported. This is a migration option, not a shutdown notice.
The catch matters for anyone watching a fast-moving bill. The new analytics guide describes a typical refresh within four hours, with delays up to 24 hours. The API suits retrospective reporting better than immediate incident detection.
Better attribution does not mean faster alerts
The legacy Console API documentation says its data typically appears within five minutes, although delays can be longer. Existing dashboards should not assume the replacement has the same freshness.
For an engineering team, those are different jobs. A weekly review asks which project drove a cost increase. An operational alarm asks whether a runaway process needs attention now. A reporting migration should preserve that distinction instead of treating every newer endpoint as a universal upgrade.
The new API can group records by model, workspace, API key or actor. Enterprise migrations also gain all populated groups rather than the old reports’ top 100 per bucket. Console access requires an Admin credential. Enterprise requires analytics access and a key with the read:analytics scope. Requests need the analytics-usage-cost-2026-08-24 beta header.
Three migration checks before changing a dashboard
| Check | New behavior | Why it matters |
|---|---|---|
| Time buckets | Use time_bucket_width, not bucket_width | Set daily buckets explicitly when preserving a daily report |
| Response shape | Rows contain group and usage or cost objects | Update the parser instead of only replacing the URL |
| Empty periods | No row for unused combinations | Fill missing periods deliberately when drawing a time series |
For a first comparison, choose a finished historical week and run both integrations without replacing the production dashboard. Compare the same dimensions and time boundaries. Investigate missing rows and changed sorting before treating a discrepancy as a change in actual consumption.
An example query to inspect, not a tested result
The usage endpoint reference supports daily buckets and model grouping. The parameters below illustrate a seven-day comparison window. ByteForward has not run this query against an account or measured its output.
starting_at=2026-10-12T00:00:00Z
ending_at=2026-10-19T00:00:00Z
time_bucket_width=1d
group_by[]=model
order_by=time
order=ascThe start is inclusive and the end exclusive. A request covers at most 31 days, with a 365-day lookback and no records before January 1, 2026. Minute buckets are limited to 24 hours. Follow next_page while has_more is true. A cursor that expires returns HTTP 410 and requires restarting pagination.
Inspect data_refreshed_at before interpreting the latest period. Data beyond it is incomplete, and monthly values can change until roughly seven days after month end. A dashboard should show that timestamp beside its totals, rather than implying that the latest displayed number is final.
Cost fields are not interchangeable
The cost reference defines amount as post-discount, pre-credit cost in fractional cents. list_amount is the pre-discount figure. Convert units before formatting dollars, and do not label either field as the final invoice total. Request counts become null when grouping by cost_type or token_type, so read counts from an ungrouped response instead.
That makes this a useful developer release for organizations building their own reporting. The adoption question is not simply whether the new endpoint returns more detail. It is whether the dashboard handles freshness, pagination, units and attribution correctly enough for the decisions people will make from it.
