Claude's new usage and cost API adds detail but lags up to 24 hours
Admins can now split Claude spend by key, user and model in one beta API, but its data refreshes in hours, not the legacy API's minutes.
If you pull Claude API usage or cost into a dashboard or a finance report, one beta API can now break it down by API key, workspace, model and the person or service account behind each request. Before you move a spend alert to it, check the clock: Anthropic's docs say its data typically lands within 4 hours, where the legacy API's typically lands within 5 minutes.
What changed#
On Oct 29, Anthropic launched the Usage and Cost Analytics API in beta (release notes). It has two endpoints, GET /v1/organizations/analytics/usage for token and request counts and GET /v1/organizations/analytics/cost for cost in USD, and they serve both Claude Console and Claude Enterprise organizations (docs). Every request needs the anthropic-beta: analytics-usage-cost-2026-08-24 header; the SDK and the ant CLI send it for you.
The old Usage and Cost API, and the usage_report, cost_report, user_usage_report and user_cost_report endpoints of the Claude Enterprise Analytics API, are now legacy. Per the release notes, "All of them remain supported."
Before and after, from Anthropic's migration guide:
| Legacy Usage and Cost API | Usage and Cost Analytics API | |
|---|---|---|
| Freshness | Typically within 5 minutes | Typically within 4 hours, up to 24 |
| Shape | Time buckets, oldest first, empty ones included | Rows ranked by a metric; no row when there's no usage |
| Time buckets | bucket_width, default 1d | time_bucket_width, no default (omit for whole-range totals) |
| Date range | Any range | On or after Jan 1, 2026, last 365 days, 31 days per request |
| Unknown key or workspace ID | Error | Matches nothing |
| Default workspace | workspace_id: null | Its real wrkspc_ ID |
| Code execution | Not in the usage report | Usage rows with model: null |
Enterprise reports also stop at the top 100 groups in each bucket; the new endpoints return every group.
Why it matters#
The new actor dimension says who a request is attributed to: a user, a service account, a federated AWS or Google Cloud identity, or the API key itself. That answers "who spent it" in one call, and the same code works for Console and Enterprise. The docs' own answer for per-user Claude Code cost is products[]=claude_code&group_by[]=actor.
The trade is time. Per the docs, "Data typically refreshes within 4 hours of the underlying usage and can take up to 24 hours." The legacy page says, "Usage and cost data typically appears within 5 minutes of API request completion, though delays might occasionally be longer." Our read: this is a reporting API, not an alarm.
How to use it#
- Get the right key. Console organizations use an Admin API key or another Admin API credential, such as an OAuth token with the
org:adminscope. Enterprise organizations use aread:analyticskey the primary owner creates in claude.ai. Anthropic suggests Workload Identity Federation where you can, so there's no long-lived key to leak. - Compare first (our read). Query a finished week from both endpoints before you switch anything.
- Rebuild the daily report. Per the guide:
time_bucket_width=1d, the samegroup_by[],limit=1000, group rows bystarting_at, fill missing days with zeros, and addorder_by=time&order=asc. - Show freshness. Usage after
data_refreshed_atis missing or partial, per the docs. - Keep fast alerts where they are (our read), on the legacy endpoint while it stays supported.
Migrate our usage dashboard from /v1/organizations/usage_report/messages to GET /v1/organizations/analytics/usage, following the "Migrate from the Usage and Cost API" section of https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api. Keep the legacy code path behind a flag. Send the analytics-usage-cost-2026-08-24 beta header, use time_bucket_width=1d with our existing group_by, page with limit=1000, and fill days with no rows with zeros. Before querying, check every workspace ID and model name we filter on, because the new API returns no rows for unknown values instead of an error. Show data_refreshed_at next to each total. Then compare one finished week from both endpoints and list every difference.
(ours, untested)
Gotchas#
- Typos fail quietly. A misspelled
models[]name or an unknown ID returns nothing, not an error. - Numbers move. Values can be revised until about 7 days after the month ends. The Analytics APIs page says, "For invoicing-grade totals, query only months that ended at least 7 days ago."
- Units. Amounts are decimal strings in cents:
"41280.000000"is $412.80.amountis after discounts and before credits;list_amountis list price. - Priority Tier. Committed requests show up with
service_tier: "priority"but zero token cost; the commitment fee isn't in this data. - Claude Platform on AWS. Each request covers only the workspaces in that endpoint's AWS region, so call every region.
- Short windows. At most 31 days per request, and 24 hours with
1mbuckets.
What to watch#
Anthropic hasn't given a retirement date for the legacy endpoints. A deprecation entry in the release notes would start the clock on moving fast alerts.
Last checked: Oct 30, 2026, 6:07 to 6:09 AM ET. What changed: first version.
Sources#
Steps
- Get the right key: an Admin API key (or an org:admin OAuth token) for Claude Console, or a read:analytics key from your primary owner for Claude Enterprise (per the docs).
- Our read: run the legacy and new queries side by side on a finished week before you switch a dashboard.
- To match a legacy daily report, set time_bucket_width=1d with the same group_by, page with limit=1000, group rows by starting_at and fill missing days with zeros (per the migration guide).
- Show data_refreshed_at beside every total; usage after that time is missing or partial (per the docs).
- Our read: keep any minutes-level spend alert on the legacy endpoint, which Anthropic says remains supported.
Migrate our usage dashboard from /v1/organizations/usage_report/messages to GET /v1/organizations/analytics/usage, following the 'Migrate from the Usage and Cost API' section of https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api. Keep the legacy code path behind a flag. Send the analytics-usage-cost-2026-08-24 beta header, use time_bucket_width=1d with our existing group_by, page with limit=1000, and fill days with no rows with zeros. Before querying, check every workspace ID and model name we filter on, because the new API returns no rows for unknown values instead of an error. Show data_refreshed_at next to each total. Then compare one finished week from both endpoints and list every difference. (ours, untested)