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

URL: https://infro.io/blog/anthropic-s-usage-and-cost-analytics-api-what-to-rebuild
Author: INFRO Editorial (https://infro.io/blog/editorial)
Publisher: INFRO
Published: 2026-11-07
Last modified: 2026-11-07
Last reviewed: 2026-11-07 (next review due 2026-12-07)
Topic: Cost and FinOps
Format: Guide

> Anthropic made the usage_report and cost_report endpoints legacy on 29 October 2026 but still supports them [^release-notes]. 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 [^analytics-api].

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.

| Legacy | New | What differs |
| --- | --- | --- |
| `GET /v1/organizations/usage_report/messages` | `GET /v1/organizations/analytics/usage` | Both give token counts; the new one adds `requests` and the actor, user profile and product dimensions |
| `GET /v1/organizations/cost_report` | `GET /v1/organizations/analytics/cost` | Legacy 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`, optional | Without 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 label | `cost_type` and `token_type` group-bys | Closest 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.[2][3][5][6]

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`.[4][6]

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](https://infro.io/blog/provider-admin-key-least-privilege).

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.[4][6] 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.

```python
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.[9][8] 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](https://infro.io/blog/reconcile-llm-spend-provider-invoices) covers that comparison in more depth.

## Questions

### 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 [1][2]. 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.

## Sources

1. Claude Platform release notes — Anthropic. https://docs.anthropic.com/en/release-notes/api (accessed 2026-11-07)
2. Usage and Cost API (legacy) — Anthropic. https://docs.anthropic.com/en/api/usage-cost-api (accessed 2026-11-07)
3. Get Cost Report (legacy API reference) — Anthropic. https://platform.claude.com/docs/en/api/beta/organization/cost_report/retrieve (accessed 2026-11-07)
4. Usage and Cost Analytics API — Anthropic. https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api (accessed 2026-11-07)
5. Get Token Usage By Dimension (API reference) — Anthropic. https://platform.claude.com/docs/en/api/beta/organization/analytics/usage/list (accessed 2026-11-07)
6. Get Cost By Dimension (API reference) — Anthropic. https://platform.claude.com/docs/en/api/beta/organization/analytics/cost/list (accessed 2026-11-07)
7. User profiles for end-customer attribution — Anthropic. https://platform.claude.com/docs/en/manage-claude/user-profiles (accessed 2026-11-07)
8. Cost attribution — INFRO. https://infro.io/docs/features/attribution (accessed 2026-11-07)
9. Cost reconciliation — INFRO. https://infro.io/docs/cost/reconciliation (accessed 2026-11-07)
