Claude Usage and Cost Analytics API: keep Console alerts on legacy

Anthropic launched the Usage and Cost Analytics API in beta on October 29, 2026. It has two endpoints, /v1/organizations/analytics/usage and /v1/organizations/analytics/cost, and it serves both Claude Console and Claude Enterprise organizations. The same release note moves the older Usage and Cost API to legacy status, along with the Claude Enterprise usage and cost report endpoints, and says all of them remain supported. The new API can show spend by user, service account, API key and model, with more grouping and filtering dimensions than the legacy API. Its data is slower, though. It typically refreshes within 4 hours and can take up to 24, while data from the legacy Claude Console API typically appears within 5 minutes. BaristaLabs view: that gap should decide which API feeds which job.

What changed in the Claude usage and cost APIs?

There are now two generations of Claude reporting endpoints, and Anthropic recommends the new one. The legacy Usage and Cost API docs now say: "For new integrations, use the Usage and Cost Analytics API."

The new endpoints need the beta header anthropic-beta: analytics-usage-cost-2026-08-24 as well as anthropic-version. The official SDK and the ant CLI send both headers. Results can be filtered and grouped by model, workspace, API key, service tier and actor, among other dimensions, with up to five group_by[] dimensions per request. The cost endpoint adds cost_type and token_type, which don't count toward the five. Some dimensions apply to only one organization type. api_key_id, for example, applies only to Claude Console, and a dimension that doesn't apply is null on every row and its filter matches nothing.

The actor dimension matters most for attribution. Anthropic defines the actor as the person or identity a request is attributed to: a user, a service account, or a federated cloud identity (an AWS or Google Cloud principal). When none of those is behind a request, the actor is the API key itself. Some requests are made without an API key, such as those from the Claude Console, from Claude Code after a sign-in without an API key, or with a Workload Identity Federation token. Those requests have api_key_id: null, but they can still have an actor. A report grouped by API key can't attribute that spend. A report grouped by actor can when the request has an actor. Usage that can't be attributed to any identity shows actor: null.

For Claude Enterprise, the legacy usage_report and cost_report endpoints return at most the top 100 groups in each time bucket. The new endpoints return every group in every bucket.

How fresh is the Usage and Cost Analytics API data?

Data typically refreshes within 4 hours of the underlying usage and can take up to 24 hours. Every response includes a data_refreshed_at timestamp, and usage after that time is missing or partial. Values can also change as late events arrive and reconciliation runs, until about 7 days after the end of the calendar month. In Anthropic's example, values for October 1 can change until about November 7.

The Analytics API docs give two rules for stable numbers. For repeated calls, set ending_at at or before a data_refreshed_at value that has already been returned. For final totals, query only months that ended at least 7 days ago.

The legacy Claude Console API is much quicker. Its docs say its data "typically appears within 5 minutes of API request completion, though delays might occasionally be longer." That figure doesn't cover Claude Enterprise. The Claude Enterprise Analytics API docs say data from its cost and usage endpoints "is typically available within 4 hours of the underlying usage but might take up to 24 hours," and the Enterprise migration table lists no freshness change.

Legacy vs. new: what changes for existing integrations

The migration table in the Analytics API docs lists these differences for Claude Console integrations:

Scroll sideways to see all 3 columns.

Comparison dimension	Usage and Cost API (legacy)	Usage and Cost Analytics API (beta)
Endpoints	/v1/organizations/usage_report/messages, /v1/organizations/cost_report	/v1/organizations/analytics/usage, /v1/organizations/analytics/cost
Data freshness	Typically within 5 minutes	Typically within 4 hours, up to 24 hours
Response shape	Time buckets, oldest first, including empty ones	Rows ranked by order_by; combinations with no usage or cost have no row
limit	Counts time buckets per page	Counts rows per page (1 to 1,000, default 20)
Date range	Any range, paged by bucket	On or after Jan. 1, 2026, within the last 365 days, at most 31 days per request (24 hours with 1m buckets); ending_at required with time_bucket_width
Identity	account_id, service_account_id	actor or actor_type, filtered with actor_ids[]
Unknown IDs in filters	Return an error	Match nothing
Default workspace	workspace_id: null	Its real workspace_id
Cost amount	Decimal string in cents, such as "123.45"	Decimal string in cents with six decimal places, such as "123.450000", plus list_amount

Three of these changes can quietly change a report's numbers without causing an error:

• Missing rows are not zeros. A daily chart built on the new API skips days with no usage unless the code fills them in. Anthropic's recipe for reproducing the legacy daily report uses time_bucket_width=1d, limit=1000 and order_by=time&order=asc. The code then groups rows by starting_at and fills missing days with zeros.
• A typo returns an empty result. An unknown API key or workspace ID, or a misspelled models[] name, now matches nothing instead of failing. A key that shows zero spend may simply have the wrong ID in the filter.
• The default workspace has a real ID. Code that treats workspace_id: null as the default workspace will stop matching it. List Workspaces also leaves the default workspace out unless include_default=true is passed.

Should spend alerts move to the new Claude usage API?

BaristaLabs recommendation for Claude Console organizations: not yet. Use the new API for attribution and month-end reporting. Keep anything that has to react within the hour on the legacy API while it remains supported. A spend check that runs every 15 minutes against data that typically refreshes within 4 hours, and can take up to 24, may not flag a runaway job until hours after it started. Two platforms can't follow this as written. The legacy endpoints aren't available on Claude Platform on AWS. Claude Models on Google Cloud (Anthropic managed) offers only the legacy usage endpoint, so cost data there comes from the new API or the Cost page in the Claude Console. The legacy docs still list budget alerts as a use case, but its cost report offers only daily buckets and leaves out Priority Tier costs. The release note and docs reviewed give no retirement date for the legacy endpoints. They say only that the endpoints remain supported. Alerts and hard caps also do different jobs, as covered in quota vs. rate limit vs. spend cap.

Claude Enterprise organizations have a different option for per-member checks. The Spend Limits API returns each member's effective monthly cap and period_to_date_spend. It needs an Admin API key with the read:spend_limits scope, and usage credits must be turned on. Anthropic's own example uses the cost endpoint to find which members to look at, then reads their current caps from /spend_limits/effective. This API isn't available to Claude Console organizations. The docs reviewed don't say how fresh period_to_date_spend is. They do warn that it can read "0" when the spend reading is temporarily unavailable, and they say to treat it as "informational, not transactional."

What the new API is better for

The new API is built for attribution and finance work, where detail matters and a delay of hours, sometimes up to a day, doesn't.

• Spend per person and per service. Group by actor to see which users, service accounts and keys spent the most in a month. For Claude Code, Anthropic's FAQ suggests products[]=claude_code&group_by[]=actor on the cost endpoint to get cost per user.
• Key spend versus identity spend. The api_key_ids[] filter matches every request a key authenticated, whoever it was attributed to. Passing the same key to actor_ids[] matches only requests where the key itself is the actor, which is how legacy workspace keys appear because they aren't linked to an identity.
• Discounted vs. list cost. Each cost row has amount, which is after discounts and before any credits are applied, and list_amount at list prices.
• Priority Tier. Requests served under a Priority Tier commitment show zero token cost, because the commitment covers them. The commitment fee is billed separately and isn't in this data. BaristaLabs interpretation: a cost report for a team on Priority Tier understates its total Claude spend unless the commitment fee is added from billing.

The ownership problem behind attribution is the same on other platforms, as covered in how OpenAI API-key cost reporting depends on workload ownership.

Who can call it, including on AWS and Google Cloud

Claude Console organizations use an Admin API key or another Admin API credential, such as an OAuth token with the org:admin scope. Anthropic suggests a Workload Identity Federation rule with the org:admin scope where possible, so the reporting service gets short-lived tokens and has no long-lived key to leak. Claude Enterprise organizations use a key with the read:analytics scope, which the primary owner creates in claude.ai.

Both endpoints also work on these two cloud offerings:

• Claude Platform on AWS: AWS IAM authorizes requests through the ListAccountUsage and ListAccountCost actions. Each request covers only the workspaces in the AWS region of the endpoint being called, so a full organization view needs one call per region. Some dimensions, including user_profile_id and the Claude Managed Agents fields, are null on every row.
• Claude Models on Google Cloud (Anthropic managed): requests use the organization-level base URL with Google Cloud credentials. /usage needs the usageAnalytics.list IAM permission and /cost needs costAnalytics.list. The difference between that offering and Vertex AI is covered in Claude on Google Cloud: Anthropic managed vs Vertex.

Recommended first step: reconcile one closed month

BaristaLabs recommendation: where both APIs offer cost data, pull September 2026 from each. It ended more than 7 days ago, so under the Analytics API docs its totals should be final. The legacy docs give no revision window. Compare daily cost totals from the legacy cost report with the new cost endpoint, using time_bucket_width=1d, every page of results and zero-filled days. Then rerun the new query with group_by[]=actor and check how much spend lands on actor: null or on bare API keys. That share is spend the API can't tie to a person or service account. Keep a Claude Console alerting job on the legacy API, and make any new report fail loudly when a filtered query returns no rows, since a mistyped ID now returns an empty result instead of an error. Check data_refreshed_at first: a null value with empty data means no data is available yet, not a bad filter.

Sources and scope

• Claude Platform release notes, entry for October 29, 2026, accessed November 1, 2026.
• Claude Platform docs, Usage and Cost Analytics API, accessed November 1, 2026.
• Claude Platform docs, Usage and Cost API (legacy), accessed November 1, 2026.
• Claude Platform docs, Spend Limits API, accessed November 1, 2026.

The freshness figures are Anthropic's stated typical and maximum delays, not measurements, and the Analytics API is in beta, so its details can change. For help deciding which reports and alerts move, see AI consulting.