Claude Usage and Cost Analytics API Tutorial (2026): Track Token Spend by Model and Key

On October 29, 2026, Anthropic launched the Usage and Cost Analytics API in beta. In the same release notes, it marked the older Usage and Cost API as legacy. That matters if you run Claude in production and you have been checking spend by clicking through the Console or by scraping the usage page. Now there is an official endpoint pair that returns token counts and USD cost, grouped the way you actually need to read them.

This guide covers what the endpoints return, how to call them, and what to change if you already have a cost script on the old API.

Current Claude prices you will want to track

Cost reports are only useful if you can check them against list prices. These figures come from Anthropic's pricing documentation for Claude Opus 5.5, with rates in USD per 1M tokens.

Fast mode is billed at twice the standard rate. It is not available on the Batch API or Priority Tier, so a cost report that shows fast-mode spend on a batch workload means something is misconfigured.

Why this matters more than the old dashboard

The Console dashboard tells you what you spent. The analytics API lets you ask who spent it. Group by API key and you can see which service is burning budget. Group by workspace and you can charge internal teams back. Group by service tier and you can confirm that fast mode is only used where you meant it.

Opus 5.5 also makes this more pressing. Its standard input price is $4 per million tokens, and fast mode is $8. A background job that quietly switched to fast mode after a config change can double its bill without anyone noticing on a weekly summary.

Call the usage endpoint with curl

Start with the usage endpoint. This pulls one week of daily buckets, grouped by model:

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?starting_at=2026-10-26T00:00:00Z&ending_at=2026-11-02T00: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_ADMIN_KEY"

Use --globoff so curl does not interpret the brackets in group_by[]. Keep the admin key in an environment variable or a secrets manager, never in a script you commit.

Python: pull usage with requests

If you are not using the official SDK, a plain HTTP call is enough. The endpoint is paginated, so follow the pagination cursor in each response until it is empty. The SDK does this for you.

import os
import requests

BASE = "https://api.anthropic.com/v1/organizations/analytics/usage"
HEADERS = {
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "analytics-usage-cost-2026-08-24",
    "x-api-key": os.environ["ANTHROPIC_ADMIN_KEY"],
}

def fetch_usage(start: str, end: str) -> dict:
    params = {
        "starting_at": start,
        "ending_at": end,
        "time_bucket_width": "1d",
        "group_by[]": "model",
        "limit": 10,
    }
    resp = requests.get(BASE, headers=HEADERS, params=params, timeout=30)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    report = fetch_usage("2026-10-26T00:00:00Z", "2026-11-02T00:00:00Z")
    print(report)

Print the raw response the first time you run it, then write your parser against the fields you actually see. Keep the beta header in one constant so you can update it in one place when Anthropic moves the feature out of beta.

Node.js: the same request with fetch

const BASE = "https://api.anthropic.com/v1/organizations/analytics/usage";

async function fetchUsage(start, end) {
  const params = new URLSearchParams();
  params.set("starting_at", start);
  params.set("ending_at", end);
  params.set("time_bucket_width", "1d");
  params.append("group_by[]", "model");
  params.set("limit", "10");

  const res = await fetch(`${BASE}?${params}`, {
    headers: {
      "anthropic-version": "2023-06-01",
      "anthropic-beta": "analytics-usage-cost-2026-08-24",
      "x-api-key": process.env.ANTHROPIC_ADMIN_KEY,
    },
  });

  if (!res.ok) {
    throw new Error(`analytics request failed: ${res.status} ${await res.text()}`);
  }
  return res.json();
}

fetchUsage("2026-10-26T00:00:00Z", "2026-11-02T00:00:00Z")
  .then((report) => console.log(JSON.stringify(report, null, 2)))
  .catch((err) => {
    console.error(err);
    process.exit(1);
  });

Set up a separate key for the collector

An Admin API key can do a lot more than read analytics. Anthropic's own guidance is to give the collector its own key, set an expiration, and rotate it. Where you can, use Workload Identity Federation with the org:admin scope so the job gets short-lived tokens and there is no long-lived secret to leak. Treat the analytics data as sensitive. It names your API keys, workspaces, and the people behind requests.

Migrating from the legacy Usage and Cost API

If you already pull reports from the older endpoints, you do not need to switch today. They remain supported. Still, the analytics endpoints offer finer grouping, and new features will land there first. Anthropic's migration guide maps the old report fields to the new ones. Move one report at a time and compare totals for a few days before you retire the old job.

One more practical point. If you reach Claude through a gateway or a reseller such as KissAPI, the analytics endpoints only see the organization that owns the Admin key. Your gateway logs and your Anthropic org report will not match line for line, so decide early which one is the source of truth for billing. For most teams, the Anthropic report wins for cost and the gateway logs win for per-customer attribution.

Compare the Opus options before you pick a tier

Fast mode is only worth it when latency matters more than cost. This table lines up the two Opus tiers that show up in most cost reports right now.

If your cost report shows Opus 4.8 fast-mode spend, that line will stop working at the end of November. Move those calls to Opus 5.5 and check the breaking changes first. Opus 5.5 always uses adaptive thinking, does not accept temperature, top_p, or top_k, and returns a 400 for tool_choice set to any or tool. Our earlier migration guide covers those changes in detail.

Frequently asked questions

What is the Claude Usage and Cost Analytics API?

It is a beta API that reports historical token usage and USD cost for a Claude Console or Claude Enterprise organization. You group results by model, workspace, API key, or service tier.

Which header do I need?

Send anthropic-beta: analytics-usage-cost-2026-08-24 and an anthropic-version header on every request.

Is the old Usage and Cost API still working?

Yes. It is legacy as of October 29, 2026, and all of its endpoints remain supported. Anthropic published a migration guide if you want to move.