Skip to content

Cost and FinOpsGuide

Anthropic's Usage and Cost Analytics API: what to rebuild

On 29 October 2026 Anthropic marked its Usage and Cost API legacy and launched a beta Usage and Cost Analytics API. This guide maps the old reports to the new endpoints and sorts the fields into team attribution, invoice reconciliation and things to verify first.

By INFRO Editorial

Published

10 min read

Glowing token streams being compressed into a precise efficient AI infrastructure pipeline

In short

Anthropic made the usage_report and cost_report endpoints legacy on 29 October 2026 but still supports them 1. The replacement is a beta pair, /analytics/usage and /analytics/cost, with up to five group-by dimensions per query, so rebuild the pull job around workspace, API key, actor and user profile 4.

Key takeaways

  • The old usage_report and cost_report endpoints are legacy but still supported, so migrate on your schedule, not in an emergency.
  • The new cost endpoint can group by workspace, API key, actor, user profile, model, service tier, speed, context window and inference geography, up to five at a time.
  • For team attribution, Anthropic gives you workspace, key and identity; anything finer has to come from your own request metadata.
  • For invoice reconciliation, group by the price-changing dimensions and check that grouped rows sum to the ungrouped total before comparing with the invoice.
  • The new API is beta and starts at 2026-01-01, so archive old legacy history and pin the beta header.

What changed, and what did not

On 29 October 2026 Anthropic launched the Usage and Cost Analytics API in beta. Its /v1/organizations/analytics/usage and /v1/organizations/analytics/cost endpoints report token usage and cost for Claude Console and Claude Enterprise organizations, with filtering and grouping by model, workspace, API key, and the user or service account behind each request. The same release note declared the older Usage and Cost API legacy, along with four Claude Enterprise Analytics API reports: usage_report, cost_report, user_usage_report and user_cost_report. All of them remain supported.1

So this is a planned rebuild, not an outage. The legacy page itself says to use the new API for new integrations, because it reports usage and cost with more grouping and filtering dimensions.2 If a job that pulls /v1/organizations/cost_report into a spreadsheet works today, nothing forces a change this week. Two things argue for moving anyway:

  • Per-team and per-identity attribution needs dimensions the legacy cost report does not offer. Its group_by accepts only description or workspace_id.3
  • The legacy endpoints are not available everywhere. On Claude Platform on AWS the legacy endpoints are unavailable, and on Claude Models on Google Cloud (Anthropic managed) only the legacy usage endpoint is.2

The new API is beta. It requires an anthropic-beta: analytics-usage-cost-2026-08-24 header plus an anthropic-version header on every request, and the SDK and ant CLI send both for you.4 Pin the beta header in your own code and expect fields to move.

Map each old report to the new one

The mapping below is built from the parameter lists of the legacy and new endpoints. Anthropic also publishes its own migration section; it was cut off in the copy I could read, so check the table against it before you cut over.

LegacyNewWhat differs
GET /v1/organizations/usage_report/messagesGET /v1/organizations/analytics/usageBoth give token counts; the new one adds requests and the actor, user profile and product dimensions
GET /v1/organizations/cost_reportGET /v1/organizations/analytics/costLegacy groups only by description or workspace_id; new groups by up to five dimensions
Fixed daily buckets on cost (bucket_width is 1d)time_bucket_width of 1m, 1h or 1d, optionalWithout a bucket width you get one row per combination for the whole range
limit counts time buckets (default 7, max 31)limit counts rows (default 20, max 1000)Pagination logic changes meaning
description text such as a model and token labelcost_type and token_type group-bysClosest replacement in my reading; confirm on live data

Sources for the table: the legacy usage and cost pages, the legacy cost reference, and the two new reference pages.2356

Three behavioural changes matter more than the renamed paths. First, a dimension is null in group unless you list it in group_by[], and each row is one combination of the grouped dimensions. Second, buckets with no usage or cost produce no rows, so a time series needs zero-filling. Third, the range may span at most 31 days, and starting_at must be within the last 365 days and no earlier than 2026-01-01T00:00:00Z.46

That last limit has a practical consequence. Whatever history you want from before 2026 has to come out of the legacy endpoints or your own store before you retire that job. I did not read how far back the legacy endpoints reach, so check it rather than assume.

Credentials and where each endpoint works

Claude Console organizations call the new endpoints with an Admin API key or another Admin API credential, such as an OAuth token with the org:admin scope sent as a bearer token. Claude Enterprise organizations use a key with the read:analytics scope that the primary owner creates in claude.ai.4 The reference pages say the endpoints need an API key with read:analytics or an Admin API key.5

The legacy page is stricter about what fails: workspace API keys don't work against the legacy endpoints.2 The same legacy page lists Admin API key, OAuth with org:admin, or a personal or service account key not scoped to a workspace as valid credentials.

For the collector, Anthropic recommends a dedicated key for the service that collects this data, held in a secrets manager and rotated, with a key expiration set to enforce rotation. Where you can, use a Workload Identity Federation rule with the org:admin scope instead, so the service gets short-lived tokens and no long-lived key sits around.4 That is the cleanest way to reduce what an admin key can do in a reporting job, and it pairs with the guidance in least privilege for provider admin keys.

Platform differences to note:

  • Claude Platform on AWS: both endpoints are available, requests use the AWS base URL and IAM actions ListAccountUsage and ListAccountCost, and each request covers only the workspaces in the region of the endpoint you call. You call each region to cover the whole organization.4
  • Claude Models on Google Cloud (Anthropic managed): both endpoints are available with Google Cloud credentials and the usageAnalytics.list and costAnalytics.list permissions.4

Fields that can feed per-team attribution

Anthropic has no "team" field on a Messages API request in anything I read. What it gives you are identifiers, and attribution is a join between those and your own org chart. The useful dimensions for a Claude Console organization are these.

  • workspace_id: the coarsest and most stable. If each team has a workspace, this is already a team report. It is available on the cost endpoint's group-by list.6
  • api_key_id: applies to Claude Console organizations only. Usage with no key, such as requests from the Console or with a Workload Identity Federation token, has a null api_key_id.4 Resolve key IDs to names and owners with the List API Keys endpoint, and keep that mapping in a table you version.
  • actor and actor_type: who the request is attributed to: a user, a service account, a federated cloud identity, or the key itself when none of those applies. Personal and service account keys act as their linked identity and show the key in api_key_id; legacy workspace keys appear as both actor and key; usage that can't be attributed has actor: null.4
  • user_profile_id: the end-customer dimension. You register a profile per end customer, store the uprof_ ID, and send it in the anthropic-user-profile-id header. Anthropic says profiles don't change billing or pricing on their own.7 On Claude Platform on AWS this dimension is null on every row.4

Two cautions. Managed Agents sessions can be attributed to an Anthropic-managed service account (svac_...) with a null api_key_id, so an agent workload can fall outside a key-based report.4 And a filter on api_key_ids[] matches every request the key authenticated, while actor_ids[]=apikey_... matches only requests attributed to the key itself. Pick one on purpose.4

rbac_group_id exists for teams, but it is a user-group dimension that returns an error when teams aren't available to your organization.4 Don't build a Console API team report on it.

Anything finer than workspace, key, actor and profile (feature, workflow, ticket queue) must come from your side. A gateway that stamps each request can do this; INFRO's attribution docs describe workflow, feature and user_id metadata plus up to five promoted tags such as team, grouped through its own usage endpoint.8 Use Anthropic's report as the control total and your own request records as the breakdown.

Fields that can feed invoice reconciliation

The cost endpoint returns USD, one row per combination of grouped dimensions. group_by takes at most five dimensions, not counting cost_type and token_type. cost_type returns one row per cost component (tokens, web search, code execution, and session_usage for Managed Agents session time), and token_type returns one row per token type.6 That is the grain an invoice line is closest to.

The dimensions that explain why one token costs a different amount from another are the ones to group by when a month does not tie out:

  • model
  • service_tier, with values batch, flex, flex_discount, priority, priority_on_demand and standard
  • speed, fast or standard
  • context_window, 0-200k or 200k-1M
  • inference_geo, global, us or not_available

All five appear as filters and group-bys on the cost endpoint.6 The legacy cost report already carried most of them in its result rows, along with amount as a decimal string and currency.3 Keep amounts as decimals, not floats.

Rules that keep a reconciliation honest:

  1. Check the total first. Run the cost query with no group_by and no bucket width for the range; that returns a single row for the whole range.4 Your grouped rows must sum to it. If they don't, you dropped a page or a null-dimension row.
  2. Cut ranges on UTC days and split months. Buckets are UTC, and a range spans at most 31 days.46 Match the boundaries to your invoice period, which I did not verify from Anthropic's side.
  3. Store data_refreshed_at. The usage response carries it.4 Re-pull the trailing days instead of assuming a closed day is final.
  4. Treat order_by=list_amount as a lead, not a fact. The cost endpoint accepts amount, list_amount or time.6 The part of the reference I read does not define list_amount, so confirm what it means on the live page before you use it to estimate a negotiated-rate gap.

INFRO's reconciliation compares its own per-request estimates with what the provider's cost API reports per UTC day, and the doc I read names GET /v1/organizations/cost_report for Anthropic.9 That is the legacy endpoint, which Anthropic still supports. I did not read any statement from INFRO about moving to the new one, so ask before assuming which endpoint a given tool reads.

A rebuild sketch

This pulls daily cost grouped by workspace and model with the price-changing dimensions, pages through every row, and stores the raw payload. It does not assume the field names inside each row's cost object, which the pages I read did not spell out.

pull_claude_cost.py
import os, json, requests

BASE = "https://api.anthropic.com/v1/organizations/analytics/cost"
HEADERS = {
    "x-api-key": os.environ["ANTHROPIC_ADMIN_KEY"],
    "anthropic-version": "2026-10-21",
    "anthropic-beta": "analytics-usage-cost-2026-08-24",
    "User-Agent": "FinopsPull/1.0 (https://example.com)",
}

def pull(start, end):
    params = {
        "starting_at": start,          # e.g. 2026-10-01T00:00:00Z
        "ending_at": end,              # exclusive, at most 31 days later
        "time_bucket_width": "1d",
        "order_by": "time",
        "order": "asc",
        "limit": 1000,
        "group_by[]": ["workspace_id", "model", "service_tier",
                       "speed", "context_window"],
    }
    rows = []
    while True:
        r = requests.get(BASE, headers=HEADERS, params=params, timeout=60)
        r.raise_for_status()
        body = r.json()
        rows.extend(body["data"])
        if not body.get("has_more"):
            return rows, body.get("data_refreshed_at")
        params["page"] = body["next_page"]

rows, refreshed = pull("2026-10-01T00:00:00Z", "2026-11-01T00:00:00Z")
with open("claude_cost_2026_10.jsonl", "w") as f:
    for row in rows:
        f.write(json.dumps(row) + "\n")
print(len(rows), "rows; data_refreshed_at:", refreshed)

Whether the cost response carries data_refreshed_at the way the usage example does is something to confirm; the code uses .get. Run the same range with no group_by and compare totals before trusting the grouped file.

Failure modes to test before you cut over

  • Silent nulls. A dimension you did not group by is null, and a dimension that does not apply to your organization is null on every row with a filter that matches nothing.4 A team report filtered by api_key_ids[] on an organization where keys do not apply returns nothing, not an error.
  • Missing days. Empty buckets produce no rows. A chart that skips them draws a false trend.4
  • Cardinality. Five group-bys across model, tier, speed, context window and workspace can return many rows. limit has a maximum of 1000, and every combination is returned across pages, not a capped top set.6 Follow next_page until has_more is false.
  • Deleted users. exclude_deleted_users drops rows whose actor is a deleted user, but it requires group_by[]=actor, and a page may then hold fewer than limit rows.6 Leave it off in a reconciliation job, or the total will not tie.
  • Beta drift. The header name carries a date, analytics-usage-cost-2026-08-24, and the release note calls the API a beta.1 Run the old and new jobs in parallel for at least one full invoice cycle and diff the totals before turning the legacy job off.

Where a gateway helps, and where it does not

Anthropic's report is the provider's record of what it will bill. A gateway keeps its own record of each request, which is what lets you break a workspace total down by feature or customer. INFRO records estimated provider cost per request and can group it by project, key, model or attributed metadata, and its daily reconciliation compares that estimate with Anthropic's reported cost using a separate admin credential.98 It is a cross-check, not a replacement for Anthropic's numbers. Request-level estimates cannot see traffic that never passed through the gateway, so keep Anthropic's workspace and key totals as the control and compare the two. The reconciliation article covers that comparison in more depth.

Questions readers ask

Do I have to migrate off usage_report and cost_report now?
Not on a deadline Anthropic has published in the pages I read. The release notes say the legacy endpoints remain supported, and the legacy page says to use the new API for new integrations 12. Plan the move, but a job that works today is not broken.
Can the cost endpoint tell me which team spent the money?
Only through identifiers Anthropic knows: workspace, API key, actor and user profile 6. There is no free-form team tag in the parameters I read, so map workspaces and keys to teams in your own table, or carry a team tag in your own request metadata.

From the team that builds it

Where this shows up in INFRO

INFRO is a control plane in front of the provider accounts you already hold. The capabilities below are the parts of it this article touches, each with the documentation that defines its behaviour.

  • Provider cost reconciliation

    Available with a plan

    Daily comparison of estimated spend against the cost reported by OpenAI's and Anthropic's own cost APIs, using a separate admin credential, with the likely cause of a persistent gap and a suggested rate you can apply. Included on every plan.

    Read the documentation for Provider cost reconciliation
  • Spend attribution

    Available with a plan

    Group cost by model, project, key, or an end-user id you attach to the request.

    Read the documentation for Spend attribution
  • Usage and cost per request

    Available with a plan

    Every request records its model, latency, token or unit counts, and estimated provider cost, queryable by project and key.

    Read the documentation for Usage and cost per request
  • Usage, request and FOCUS exports

    Available with a plan

    GET /v1/usage and GET /v1/requests on any gateway key, the request log and usage series as CSV, plus a FOCUS v1.4 Cost and Usage dataset as JSON or CSV, so AI spend lands in your FinOps platform beside the rest of your cloud cost.

    Read the documentation for Usage, request and FOCUS exports

INFRO accounts are self-serve. Provider usage is billed to you by your providers; INFRO charges a software subscription and takes 0% of model spend. See plans.

Sources

Numbered in order of first citation. Each was opened and checked against the claim on the date shown.

  1. 1.Claude Platform release notes (opens in a new tab) — Anthropic. Accessed Nov 7, 2026.
  2. 2.Usage and Cost API (legacy) (opens in a new tab) — Anthropic. Accessed Nov 7, 2026.
  3. 3.Get Cost Report (legacy API reference) (opens in a new tab) — Anthropic. Accessed Nov 7, 2026.
  4. 4.Usage and Cost Analytics API (opens in a new tab) — Anthropic. Accessed Nov 7, 2026.
  5. 5.Get Token Usage By Dimension (API reference) (opens in a new tab) — Anthropic. Accessed Nov 7, 2026.
  6. 6.Get Cost By Dimension (API reference) (opens in a new tab) — Anthropic. Accessed Nov 7, 2026.
  7. 7.User profiles for end-customer attribution (opens in a new tab) — Anthropic. Accessed Nov 7, 2026.
  8. 8.Cost attribution (opens in a new tab) — INFRO. Accessed Nov 7, 2026.
  9. 9.Cost reconciliation (opens in a new tab) — INFRO. Accessed Nov 7, 2026.

About this article

Read on 7 November 2026: Anthropic's Claude Platform release notes, the legacy Usage and Cost API page, the new Usage and Cost Analytics API page and its usage and cost reference pages, the legacy cost report reference, the user profiles page, and INFRO's reconciliation and attribution docs. The migration section of the Analytics API page was truncated in what I could read, so the mapping is built from the two parameter lists, not from Anthropic's own migration table; response field names inside the cost object and the meaning of list_amount are left as unconfirmed.

Last checked against its sources on . The next review is due by . No separate named reviewer is recorded for this article.

How articles are written, sourced and corrected is set out in the editorial standards.