Anthropic Usage and Cost Analytics API: Migration Guide

Anthropic launched a unified beta Analytics API on 2026-10-29. Learn how to query token spend, group by actors, and migrate legacy reports.

By ailog · Published Nov 2, 2026 · 6 min read · How we work
In short
  • Anthropic launched the beta Usage and Cost Analytics API on 2026-10-29 using the analytics-usage-cost-2026-08-24 beta header.
  • The new GET /v1/organizations/analytics/usage and GET /v1/organizations/analytics/cost endpoints unify reporting for Claude Console and Claude Enterprise organizations.
  • Developers can group by up to 5 dimensions simultaneously, including actors, workspaces, service tiers, and API keys.
  • Previous reporting endpoints across Claude Console and Claude Enterprise are now classified as legacy APIs but remain supported.
  • Costs are returned in USD decimal strings in cents, with preliminary figures visible in 4 hours and revisions finalizing 7 days after month-end.

Unified Usage and Cost Reporting Across Claude Deployments

On 2026-10-29, Anthropic introduced the beta Usage and Cost Analytics API to resolve a long-standing architectural split in organizational monitoring. Historically, teams managing developer credentials through the Claude Console relied on the Admin API usage reports, while Claude Enterprise teams were forced to call disparate workspace and user reporting routes. The release establishes two unified endpoints under the Claude Platform: GET /v1/organizations/analytics/usage for token tallies and request counts, and GET /v1/organizations/analytics/cost for financial spend in USD.

Both endpoints serve Claude Console accounts and Claude Enterprise organizations identically. By sending the anthropic-beta: analytics-usage-cost-2026-08-24 header alongside the standard anthropic-version: 2023-06-01 header, developers can query historical usage and calculate precise allocations down to individual user identities, workspaces, and service accounts. Engineering teams tracking multi-model cost structures can cross-reference their query results with our /tools/llm-api-cost-calculator/ or explore tier variations on the /tools/llm-api-pricing/ index.

Existing telemetry routes have transitioned to legacy status. These include /v1/organizations/usage_report/messages and /v1/organizations/cost_report from the legacy Usage and Cost API, along with the Enterprise Analytics routes: usage_report, cost_report, user_usage_report, and user_cost_report. While Anthropic continues to support these endpoints, new telemetry features and multi-dimension slicing are restricted to the new analytics service.

Authentication Credentials and Access Scopes

Authentication mechanics depend on the administrative origin of the organization. Claude Console setups require an Admin API key (sk-ant-admin01-...) passed via the x-api-key header, or an OAuth credential generated with the org:admin scope passed in the standard authorization: Bearer header. Personal keys or service account credentials unconfined to specific workspaces can also execute queries, but ordinary workspace-scoped keys are rejected.

For enterprise administrators, Claude Enterprise parent organizations do not show up inside Claude Console and cannot hold Admin API keys. Instead, the primary owner must visit claude.ai organization settings, enable API access, and issue a dedicated Analytics API key configured with the read:analytics scope. This single key type allows enterprise customers to tap directly into the unified analytics suite.

  • Claude Console: Provide an Admin API key in x-api-key or an OAuth token bearing org:admin in authorization: Bearer.
  • Claude Enterprise: Authorize requests using an Analytics API key carrying the read:analytics permission scope.
  • Secrets Hygiene: When employing Admin API keys, assign an explicit expiration time upon creation and rotate credentials regularly.
  • Workload Identity Federation: Services can adopt short-lived tokens via federated rules scoped to org:admin rather than storing static keys.
  • Individual Accounts: Admin API telemetry routes are unavailable for individual user profiles until an organization is established.

Grouping Dimensions, Filtering Syntax, and Actor Identity Attribution

The API accepts up to 5 grouping dimensions inside a single query via the group_by[] array parameter. Unselected dimensions return as null inside the returned group object. Every returned record represents a unique combination of your requested grouped dimensions. When querying aggregate sums without grouping flags or time buckets, the endpoint emits a single row covering the entire specified window.

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
time_bucket_width=1d&\
group_by[]=model&\
limit=10" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

Filtering operates concurrently with grouping. Administrators can supply list filters in bracket notation, such as models[]=claude-opus-5-5, supplying up to 100 values per filter parameter. Multiple values within the same dimension key evaluate using OR logic, whereas distinct parameter keys evaluate using AND logic. Notably, you can filter by dimensions without including them in group_by[].

A major addition is the actor dimension, attributing usage to human users, service accounts, federated identities, or unlinked keys. The table below outlines how actor attribution operates across distinct authentication pathways:

  • Personal and Service Account Keys: The linked user profile or service account populates the actor object, and api_key_id holds the credential identifier.
  • Legacy Workspace Keys: Unlinked keys display their key identifier within both the actor object and api_key_id.
  • Claude Code Auto-Created Keys: Keys generated during member login report that specific human member as the actor.
  • Unauthenticated or Federated Calls: Requests without explicit API keys display null for api_key_id, while actor identifies the member or workload service account.
  • Targeting Unassigned Requests: Add an empty filter entry (api_key_ids[]=) to capture workload traffic that carries no API key.

Comparing Legacy Reporting Endpoints to the Analytics API

Engineering teams currently consuming the legacy reporting endpoints must understand the functional discrepancies before refactoring extraction jobs. Legacy endpoints forced disparate querying conventions, restricted granularity in cost data, and limited grouping mechanics. The following matrix contrasts operational boundaries across both designs.

Feature / Dimension Legacy Reporting Routes Beta Usage and Cost Analytics API
Endpoint Routes /v1/organizations/usage_report/messages & cost_report /v1/organizations/analytics/usage & cost
Enterprise Parity Separate user and enterprise usage report paths Identical endpoints and parameters for Console and Enterprise
Multi-Grouping Single or constrained parameter grouping Combine up to 5 dimensions per request simultaneously
Identity Attribution Key ID only; no unified actor structure Detailed actor object (user, service account, or key)
Cost Bucketing Daily (1d) intervals only 1m, 1h, or 1d time bucket width options
AWS & Google Cloud Support Limited regional or usage-only availability Full IAM integration across AWS and Google Cloud managed environments

Token tracking across the usage route categorizes tokens into uncached input, cache creation (including ephemeral_5m_input_tokens and ephemeral_1h_input_tokens), cache read input, and output tokens. For teams analyzing cache hit performance alongside billing, our breakdown on /posts/prompt-caching-explained-claude-gpt-gemini/ details how these cached input ratios reduce expenditures.

Time Buckets, Multi-Cloud Deployments, and Data Freshness Rules

Time series analytics can be divided into UTC intervals using time_bucket_width set to 1m, 1h, or 1d. Buckets without recorded usage or cost are omitted from the payload rather than zero-filled. Queries default to descending sort based on order_by metrics (such as total_tokens, output_tokens, uncached_input_tokens, requests, or time). Setting order_by=time sorts data bucket by bucket, allowing applications to iterate chronologically when paired with order=asc.

Data arrival follows distinct settlement cycles. Usage and cost records typically appear within 4 hours of generation, though processing can extend to 24 hours. Because accounting pipelines reconcile late records, values remain subject to adjustment until approximately 7 days following the end of the calendar month. For example, usage generated on October 1 can experience revisions until November 7. Responses present a data_refreshed_at timestamp; setting ending_at prior to this timestamp ensures reproducible, frozen data extractions.

Cloud-native implementations operate through specialized authorization bindings:

  • Claude Platform on AWS: Replaces Admin keys with AWS IAM actions ListAccountUsage and ListAccountCost. Queries cover workspaces within the specific regional endpoint called.
  • AWS Null Dimensions: On AWS endpoints, user_profile_id, claude_tag_category, claude_tag_user_id, agent_id, environment_id, deployment_id, and session_id always return null.
  • Google Cloud Managed: Uses organization base URLs authenticated by Google Cloud credentials. The /usage path requires usageAnalytics.list, while /cost requires costAnalytics.list.
  • Currency Representation: Amounts in the cost endpoint are returned as USD decimal strings representing lowest units in cents (e.g., ‘41280.000000’ equals $412.80). Always parse as decimals rather than binary floats.
  • Excluded Tiers: Priority Tier billings utilize a distinct billing framework and are omitted from /cost; track Priority Tier volume via /usage.

Migration Checklist for Engineering and FinOps Pipelines

Migrating ingestion scripts from legacy reporting to the new analytics suite requires updating headers, query parameters, and schema decoders. Complete the following verification steps before retiring legacy jobs:

  • Update Beta Header: Inject anthropic-beta: analytics-usage-cost-2026-08-24 on every GET request alongside anthropic-version: 2023-06-01.
  • Redirect URL Paths: Transition Console endpoints to /v1/organizations/analytics/usage and /v1/organizations/analytics/cost.
  • Refactor Cursors: Ensure pagination cursors (next_page) are never reused after changing filters, group parameters, or date windows, which causes 400 errors.
  • Convert Monetary Units: Update billing ingest pipelines to divide cents strings by 100 to yield USD dollar balances.
  • Establish Invoicing Windows: Avoid sealing internal monthly billing ledgers until at least 7 days after the month closes to account for reconciliation adjustments.
  • Adopt Auto-Pagination: Use official SDK iterators (in Python, TypeScript, Go, Java, C#, PHP, or Ruby) or CLI commands to streamline next_page resolution.

For broader architectural patterns regarding rate tiers, context windows, and model cost allocation across providers, refer to /posts/rate-limits-and-usage-tiers-at-anthropic-openai-and-google/ and /posts/choosing-an-llm-api-model-by-cost-tier/.

Sources
  1. Anthropic Claude Platform release notes — 2026-10-29
  2. Usage and Cost Analytics API
  3. Usage and Cost API
  4. Analytics APIs

Related