Usage and Cost Analytics API

Die Usage and Cost Analytics API liefert die historische Token-Nutzung und die Kosten deiner Organisation, aufgeschlüsselt nach den von dir gewählten Dimensionen, etwa Modell, Workspace, API-Key oder dem Benutzer bzw. Service-Account hinter jeder Anfrage. Für Claude Console-Organisationen ähneln diese Daten dem, was die Seiten Usage und Cost der Claude Console anzeigen.

Die API hat zwei Endpunkte:

• GET /v1/organizations/analytics/usage liefert Token-Anzahlen und Anfrageanzahlen.
• GET /v1/organizations/analytics/cost liefert Kosten in USD.

Die Usage and Cost Analytics API befindet sich in der Beta-Phase. Sende bei jeder Anfrage anthropic-beta: analytics-usage-cost-2026-08-24 als Header sowie einen anthropic-version-Header mit. Das SDK und die ant-CLI senden beide Header für dich und rufen die restlichen Seiten ab, während du die Ergebnisse liest, sodass limit nur die Seitengröße festlegt.

Verwende diese API, um:

• Ausgaben zuzuordnen: Kosten und Token-Nutzung nach Workspace, API-Key, Modell, Service-Tier oder der Identität aufzuschlüsseln, die die jeweilige Anfrage gestellt hat.
• Die größten Verbraucher zu finden: Ergebnisse nach Token, Anfragen oder Kosten zu sortieren, um Fragen wie „Welche API-Keys geben diesen Monat am meisten aus?“ zu beantworten.
• Zeitreihen zu erstellen: Ergebnisse für Dashboards und Finanzberichte in tägliche, stündliche oder minütliche Intervalle aufzuteilen.
• Einmal zu integrieren: Dieselben Endpunkte, Parameter und Antwortfelder bedienen Organisationen in der Claude Console und in Claude Enterprise.

Schnellstart

Rufe die tägliche Token-Nutzung für die erste Septemberwoche ab, mit einer Zeile für jedes Modell und jeden Tag:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=10,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

Die Antwort enthält eine Zeile für jedes Modell und jeden Tag mit Nutzung, die Zeile mit dem größten total_tokens zuerst. Dieses Beispiel zeigt eine einzelne Zeile:

{
  "data": [
    {
      "starting_at": "2026-09-03T00:00:00Z",
      "ending_at": "2026-09-04T00:00:00Z",
      "group": {
        "product": null,
        "model": "claude-sonnet-5",
        "context_window": null,
        "inference_geo": null,
        "speed": null,
        "slack_channel_id": null,
        "claude_tag_category": null,
        "claude_tag_user_id": null,
        "rbac_group_id": null,
        "workspace_id": null,
        "service_tier": null,
        "user_profile_id": null,
        "agent_id": null,
        "environment_id": null,
        "deployment_id": null,
        "session_id": null,
        "actor": null,
        "actor_type": null,
        "api_key_id": null
      },
      "usage": {
        "uncached_input_tokens": 1284500,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 215300
        },
        "cache_read_input_tokens": 3200000,
        "output_tokens": 891000,
        "total_tokens": 5590800,
        "server_tool_use": {
          "web_search_requests": 12
        },
        "requests": 4210
      }
    }
  ],
  "has_more": true,
  "next_page": "page_V2mQ4dkt9HcbX3pLr...",
  "data_refreshed_at": "2026-09-18T16:02:11Z"
}

Wie Ergebnisse aufgebaut sind

• Jede Zeile besteht aus drei Teilen: starting_at und ending_at geben den Zeitraum an, den die Zeile abdeckt, group enthält alle Dimensionen, und usage (bzw. cost beim Cost-Endpunkt) enthält die Metriken.
• Dimensionen sind null, sofern nicht gruppiert: Eine Dimension in group ist null, es sei denn, du führst sie in group_by[] auf. Eine gruppierte Dimension ist außerdem in Zeilen null, die keinen Wert dafür haben, etwa model bei der Nutzung von Code Execution. group_by[] akzeptiert bis zu fünf Dimensionen.
• Eine Zeile für jede Kombination: Jede Zeile ist eine Kombination der gruppierten Dimensionen, und jede Kombination mit Nutzung oder Kosten erscheint über alle Seiten einer Abfrage hinweg genau einmal. Ohne group_by[] und ohne time_bucket_width besteht die Antwort aus einer einzigen Zeile, die den gesamten Zeitraum summiert.
• Zeitintervalle sind optional: Setze time_bucket_width auf 1m, 1h oder 1d, um jede Kombination nach UTC-Zeitintervall aufzuteilen; starting_at und ending_at jeder Zeile sind dann die Grenzen ihres Zeitintervalls. Zeitintervalle ohne Nutzung oder Kosten erzeugen keine Zeilen.
• Standardmäßig nach Rang sortiert: Zeilen werden nach der order_by-Metrik über den gesamten Zeitraum sortiert, standardmäßig die größten zuerst (order=asc kehrt dies um). Um eine Zeitreihe zu erstellen, setze time_bucket_width und order_by=time. Die Zeilen werden dann ein Zeitintervall nach dem anderen zurückgegeben, standardmäßig das neueste Zeitintervall zuerst (order=asc stellt das älteste an den Anfang), wobei innerhalb jedes Zeitintervalls die größten Zeilen zuerst kommen. Fülle leere Zeitintervalle mit Nullen auf.
• Filter funktionieren zusammen mit Gruppierung: Für die meisten Dimensionen, nach denen du gruppieren kannst, gibt es einen passenden Listenfilter in Klammernotation, etwa models[]=claude-opus-5-5. Wiederhole den Parameter, um mehrere Werte zu übergeben, bis zu 100. Mehrere Werte für denselben Filter werden mit OR kombiniert, verschiedene Filter mit AND. Filter und group_by[] sind unabhängig voneinander; du kannst nach jeder Dimension filtern, mit oder ohne nach ihr zu gruppieren, und umgekehrt.

Dimensionen wie model und actor gelten für jede Organisation. Einige, etwa api_key_id, gelten nur für Claude Console-Organisationen, andere, etwa slack_channel_id, nur für Claude Enterprise-Organisationen. Eine Dimension, die nicht für deine Organisation gilt, ist in jeder Zeile null, und ihr Filter trifft auf nichts zu; die Ausnahme ist rbac_group_id, das stattdessen einen Fehler zurückgibt, wenn Teams für deine Organisation nicht verfügbar sind. Die API-Referenz für usage und cost listet jede Dimension, jeden Filter und jeden Wert auf.

Akteure

Die Dimension actor gibt an, wem eine Anfrage zugeordnet wird: einem Benutzer, einem Service-Account, einer föderierten Cloud-Identität (einem AWS- oder Google Cloud-Principal, für Organisationen, die über ihre Cloud-Plattform auf Claude zugreifen) oder, wenn keines davon hinter der Anfrage steht, dem API-Key selbst. Wenn du nach actor gruppierst, ist actor in jeder Zeile ein Objekt, dessen type angibt, um welche Art es sich handelt. Nutzung, die keiner Identität zugeordnet werden kann, hat actor: null.

Persönliche Keys und Service-Account-Keys agieren als der Benutzer oder Service-Account, mit dem sie verknüpft sind, sodass ihre Anfragen diese Identität als actor und den Key in api_key_id zeigen. Veraltete Workspace-Keys sind mit keiner Identität verknüpft, daher erscheint der Key sowohl als actor als auch als api_key_id. Die Ausnahme ist der Key, den Claude Code erstellt, wenn sich ein Mitglied mit seinem Claude Console-Konto anmeldet: Er befindet sich im Claude Code Workspace, und seine Nutzung wird diesem Mitglied zugeordnet. Anfragen ohne API-Key, etwa aus der Claude Console oder mit einem Workload Identity Federation-Token, haben api_key_id: null; der actor eines föderierten Workloads ist sein Service-Account. Um Nutzung ohne API-Key in einen api_key_ids[]-Filter einzuschließen, füge einen leeren Eintrag hinzu: api_key_ids[]=.

Die Filter api_key_ids[] und actor_ids[] beantworten unterschiedliche Fragen. api_key_ids[]=apikey_... trifft auf jede Anfrage zu, die der Key authentifiziert hat, unabhängig davon, wem sie zugeordnet ist. actor_ids[]=apikey_... trifft nur auf Anfragen zu, die dem Key selbst zugeordnet sind.

Usage-Endpunkt

GET /v1/organizations/analytics/usage gibt Token-Anzahlen nach Typ zurück. order_by akzeptiert total_tokens (Standard), output_tokens, uncached_input_tokens, requests oder time.

Um beispielsweise eine Woche Nutzung für einen Workspace und einen API-Key aufgeschlüsselt nach Service-Tier zu sehen (eine Zeile für jeden Tier, die die gesamte Woche abdeckt):

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
    group_by=["service_tier"],
)

for row in rows:
    print(f"{row.group.service_tier}: {row.usage.total_tokens}")

Um API-Key- und Workspace-IDs nachzuschlagen, verwende die Endpunkte List API Keys und List Workspaces oder die Claude Console.

Um herauszufinden, welche Benutzer, Service-Accounts und API-Keys in einem Monat die meisten Anfragen gestellt haben:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["actor"],
    order_by="requests",
    limit=25,
)

for row in rows:
    print(f"{row.group.actor}: {row.usage.requests}")

Cost-Endpunkt

GET /v1/organizations/analytics/cost akzeptiert dieselben Filter, Dimensionen und Zeitintervalle wie der /usage-Endpunkt. Das cost-Objekt jeder Zeile enthält amount (die Kosten nach Rabatten und vor der Anrechnung von Guthaben), list_amount (die Kosten zu Listenpreisen), currency (immer "USD") und requests. Beträge sind Dezimal-Strings in Cent mit sechs Nachkommastellen: "41280.000000" entspricht 412,80 $ USD. order_by akzeptiert amount (Standard), list_amount oder time.

Zwei zusätzliche Dimensionen gibt es nur bei diesem Endpunkt, und sie zählen nicht zum Limit von fünf Dimensionen: group_by[]=cost_type teilt jede Zeile in eine Zeile für jeden Kostentyp auf, und group_by[]=token_type teilt die Token-Kosten in eine Zeile für jeden Token-Typ auf. limit gilt für diese beiden Dimensionen ebenfalls nicht, sodass eine Seite mehr als limit Zeilen enthalten kann. Zum Beispiel Kosten nach Modell, Kostentyp und Token-Typ für einen Monat:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["model", "cost_type", "token_type"],
)

for row in rows:
    print(
        f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
    )

Für jedes Modell enthält die Antwort fünf tokens-Zeilen (eine für jeden Token-Typ) sowie je eine Zeile für web_search, code_execution und session_usage. Eine dieser Zeilen:

{
  "starting_at": "2026-09-01T00:00:00Z",
  "ending_at": "2026-10-01T00:00:00Z",
  "group": {
    "model": "claude-opus-5",
    ...,
    "cost_type": "tokens",
    "token_type": "cache_read_input_tokens"
  },
  "cost": {
    "currency": "USD",
    "amount": "41280.000000",
    "list_amount": "51600.000000",
    "requests": null
  }
}

Das group-Objekt enthält jede Dimension und ist hier gekürzt. Wenn group_by[]=cost_type oder token_type angegeben ist, ist requests in jeder Zeile null.

Datumsbereiche und Zeitintervalle

• Zeitstempel sind im Format RFC 3339 mit UTC-Offset, zum Beispiel 2026-09-01T00:00:00Z. starting_at ist inklusiv und ending_at exklusiv.
• starting_at muss am oder nach dem 1. Januar 2026 und innerhalb der letzten 365 Tage liegen. Eine Anfrage kann höchstens 31 Tage umfassen; ending_at ist standardmäßig 31 Tage nach starting_at oder die aktuelle Zeit, je nachdem, was früher ist.
• ending_at ist erforderlich, sobald time_bucket_width gesetzt ist, und mit time_bucket_width=1m kann eine Anfrage höchstens 24 Stunden umfassen.
• Beide Enden des Bereichs werden auf eine UTC-Intervallgrenze abgerundet, oder auf die volle Stunde, wenn time_bucket_width nicht gesetzt ist. Zum Beispiel wird mit time_bucket_width=1h ein starting_at von 2026-09-01T10:43:00Z als 2026-09-01T10:00:00Z und ein ending_at von 2026-09-01T15:43:00Z als 2026-09-01T15:00:00Z behandelt, sodass die Antwort 10:00 bis 15:00 UTC abdeckt.

Datenaktualität

Jede Antwort enthält einen data_refreshed_at-Zeitstempel, und Nutzung nach diesem Zeitpunkt fehlt oder ist unvollständig. Wenn für keinen Teil des angefragten Zeitraums bereits Daten verfügbar sind, ist data_refreshed_at null und data leer. Daten werden in der Regel innerhalb von 4 Stunden nach der zugrunde liegenden Nutzung aktualisiert, es kann aber bis zu 24 Stunden dauern. Werte können überarbeitet werden, wenn verspätete Ereignisse eintreffen und Abgleiche laufen, bis etwa 7 Tage nach Ende des Kalendermonats. Beispielsweise können sich Werte für den 1. Oktober bis etwa zum 7. November ändern. Für stabile Ergebnisse über wiederholte Aufrufe hinweg setze ending_at auf oder vor einen data_refreshed_at-Wert, den du bereits gesehen hast; für endgültige Summen frage nur Monate ab, die vor mindestens 7 Tagen geendet haben. Jede Seite einer paginierten Abfrage liest denselben Daten-Snapshot, daher ist data_refreshed_at auf allen Seiten identisch.

Migration von der Usage and Cost API

Dieser Abschnitt richtet sich an Claude Console-Organisationen, die die veraltete Usage and Cost API (/v1/organizations/usage_report/messages und /v1/organizations/cost_report) aufrufen. Dein Admin-API-Key, der anthropic-version-Header, starting_at und ending_at, die Werte für die Intervallbreite (1m, 1h, 1d), die Klammernotation, die Namen der Paginierungsfelder sowie die Namen der Token- und Kostenfelder bleiben gleich. Was sich ändert:

Um den veralteten Tagesbericht nachzubilden, fordere time_bucket_width=1d mit demselben group_by[] an, blättere mit limit=1000 durch die Seiten, gruppiere dann die Zeilen nach starting_at und fülle fehlende Tage mit Nullen auf. Füge order_by=time&order=asc hinzu, um die Tage in der richtigen Reihenfolge zu erhalten. Tägliche Nutzung nach Modell für 1 Woche, vorher:

curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

und nachher:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=1000,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

Tägliche Kosten nach Workspace, Modell, Service-Tier, Kontextfenster und Inference-Geo, aufgeteilt nach Kostentyp und Token-Typ:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=[
        "workspace_id",
        "model",
        "service_tier",
        "context_window",
        "inference_geo",
        "cost_type",
        "token_type",
    ],
    limit=1000,
)

for row in rows:
    group = row.group
    print(
        f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
        f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
        f"{row.cost.amount}"
    )

Migration von den Claude Enterprise-Nutzungs- und Kostenberichten

Dieser Abschnitt richtet sich an Claude Enterprise-Organisationen, die die Berichtsendpunkte usage_report, cost_report, user_usage_report und user_cost_report der Claude Enterprise Analytics API unter /v1/organizations/analytics/ aufrufen. Diese Endpunkte sind veraltet und werden weiterhin unterstützt. Wechsle zu /analytics/usage und /analytics/cost, wenn du eines der folgenden Dinge möchtest:

• Jede Gruppe in jedem Zeitintervall statt der 100 größten Gruppen pro Zeitintervall
• Gruppierung nach actor oder actor_type zusammen mit anderen Dimensionen, sowohl bei Nutzung als auch bei Kosten
• Zeilen, die nach einer Metrik deiner Wahl über den gesamten Zeitraum sortiert oder nach Zeitintervall geordnet sind
• Eine Integration, die auch Organisationen in der Claude Console bedient

Dein Key, das früheste Datum, der Rückblick von 365 Tagen und die Spanne von 31 Tagen, die Namen und Werte der Filter und Dimensionen (außer user_ids[] und dem Produktwert für Claude Tag), die actor-Felder für Benutzer, die Metrik- und Betragsfelder, data_refreshed_at, die Cursor-Regeln und das Ratenlimit auf Organisationsebene bleiben unverändert. Der einzige neue Header ist der Beta-Header analytics-usage-cost-2026-08-24. Was sich ändert:

Kosten pro Benutzer für einen Monat, vorher:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.user_cost_report.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    limit=100,
)

for row in rows:
    print(f"{row.actor.user_id}: {row.amount}")

und nachher, mit zusätzlicher Aufschlüsselung nach Produkt:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    actor_types=["user_actor"],
    group_by=["actor", "product"],
    limit=100,
)

for row in rows:
    actor = row.group.actor
    if actor is not None and actor.type == "user_actor":
        print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")

Häufig gestellte Fragen

Wie wird der Standard-Workspace dargestellt?

Der Standard-Workspace einer Organisation in der Claude Console hat wie jeder andere Workspace eine eigene wrkspc_-ID. Zeilen für den Standard-Workspace enthalten diese ID in workspace_id, und du kannst mit workspace_ids[] danach filtern. List Workspaces lässt den Standard-Workspace weg, es sei denn, du übergibst include_default=true. Um zu prüfen, ob eine unbekannte workspace_id der Standard-Workspace ist, übergib sie an Get Workspace: Der Standard-Workspace gibt "name": "Default" zurück.

Wie erhalte ich Kosten pro Benutzer für Claude Code?

Rufe den Cost-Endpunkt mit products[]=claude_code&group_by[]=actor auf. Claude Console-Organisationen können auch die Claude Code Analytics API verwenden, die Claude Code-Aktivität und geschätzte Kosten pro Benutzer liefert.

Siehe auch

• Usage and Cost API (veraltet)
• Analytics APIs: welche Analytics API und welchen Key-Typ deine Organisation benötigt
• Claude Code Analytics API
• Admin-API-Referenz
• Preise