Usage and Cost API

Die Usage & Cost Admin API bietet programmatischen und granularen Zugriff auf historische API-Nutzungs- und Kostendaten deiner Organisation. Diese Daten ähneln den Informationen, die auf den Seiten Usage und Cost der Claude Console verfügbar sind.

Diese API ermöglicht es dir, deine Claude-Implementierungen besser zu überwachen, zu analysieren und zu optimieren:

• Präzises Usage-Tracking: Erhalte genaue Token-Zählungen und Nutzungsmuster, anstatt dich ausschließlich auf das Zählen von Response-Tokens zu verlassen
• Kostenabgleich: Gleiche interne Aufzeichnungen mit der Anthropic-Abrechnung für Finanz- und Buchhaltungsteams ab
• Produktleistung und -verbesserung: Überwache die Produktleistung und miss, ob Änderungen am System diese verbessert haben, oder richte Alerting ein
• Ratenlimit-Optimierung: Optimiere Features wie Prompt-Caching oder spezifische Prompts, um deine zugewiesene Kapazität optimal zu nutzen.
• Erweiterte Analyse: Führe tiefergehende Datenanalysen durch, als es in der Console möglich ist

Claude Enterprise-Organisationen verwenden stattdessen einen Analytics-API-Key mit einer anderen API; siehe Welche API brauchst du?.



Welche API brauchst du?

Anthropic bietet Kosten- und Nutzungsberichte über zwei APIs an, je nachdem, welches Claude-Produkt deine Organisation verwaltet:

Übergeordnete Claude Enterprise-Organisationen erscheinen nicht in der Claude Console und verfügen über keine Admin-API-Keys, daher ist für sie der Analytics-API-Key der einzige Weg zu diesen Daten. Siehe Analytics APIs für Informationen dazu, wie du jeden Key-Typ erstellst und für welche Pläne die Claude Enterprise-Kostendaten gelten.



Partnerlösungen

Führende Observability-Plattformen bieten einsatzbereite Integrationen zur Überwachung deiner Claude-API-Nutzung und -Kosten, ohne dass du eigenen Code schreiben musst. Diese Integrationen bieten Dashboards, Alerting und Analytics, um dir zu helfen, deine API-Nutzung effektiv zu verwalten.



Schnellstart

Rufe die tägliche Nutzung deiner Organisation für die letzten 7 Tage ab:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

User-Agent: YourApp/1.0.0 (https://yourapp.com)



Usage API

Verfolge den Token-Verbrauch in deiner gesamten Organisation mit detaillierten Aufschlüsselungen nach Modell, Workspace und Service-Tier über den Endpunkt /v1/organizations/usage_report/messages.



Zentrale Konzepte

• Zeit-Buckets: Aggregiere Nutzungsdaten in festen Intervallen (1m, 1h oder 1d)
• Token-Tracking: Miss ungecachte Input-, gecachte Input-, Cache-Erstellungs- und Output-Tokens
• Filtern & Gruppieren: Filtere nach API-Key, Workspace, Modell, Service-Tier, Kontextfenster, Data Residency oder Speed (Beta) und gruppiere Ergebnisse nach diesen Dimensionen
• Server-Tool-Nutzung: Verfolge die Nutzung serverseitiger Tools wie Websuche

Vollständige Parameterdetails und Response-Schemas findest du in der Usage-API-Referenz.



Grundlegende Beispiele



Tägliche Nutzung nach Modell

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



Stündliche Nutzung mit Filterung

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=claude-opus-4-8&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Nutzung nach API-Keys und Workspaces filtern

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Data Residency

Verfolge deine Data-Residency-Kontrollen, indem du die Nutzung mit der Dimension inference_geo gruppierst und filterst. Dies ist nützlich, um das geografische Routing in deiner Organisation zu überprüfen.

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

Du kannst auch nach einer bestimmten Geo filtern. Gültige Werte sind global, us und not_available:

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



Fast Mode (Research Preview)

Verfolge die Fast-Mode-Nutzung, indem du mit der Dimension speed gruppierst und filterst. Dies ist nützlich, um die Nutzung von Standard- vs. Fast-Mode zu überwachen.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Du kannst auch nach einer bestimmten Speed filtern. Gültige Werte sind standard und fast:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
speeds[]=fast&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Limits für Zeitgranularität



Cost API

Rufe Kostenaufschlüsselungen auf Service-Ebene in USD über den Endpunkt /v1/organizations/cost_report ab.



Zentrale Konzepte

• Währung: Alle Kosten in USD, angegeben als Dezimal-Strings in der kleinsten Einheit (Cents)
• Kostentypen: Verfolge Kosten für Token-Nutzung, Websuche und Code-Ausführung
• Gruppierung: Gruppiere Kosten nach Workspace oder Beschreibung für detaillierte Aufschlüsselungen. Bei Gruppierung nach description enthalten die Responses geparste Felder wie model und inference_geo
• Zeit-Buckets: Nur tägliche Granularität (1d)

Vollständige Parameterdetails und Response-Schemas findest du in der Cost-API-Referenz.



Grundlegendes Beispiel

curl "https://api.anthropic.com/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Paginierung

Beide Endpunkte unterstützen Paginierung für große Datensätze:

1. Stelle deine erste Anfrage
2. Wenn has_more true ist, verwende den next_page-Wert in deiner nächsten Anfrage
3. Fahre fort, bis has_more false ist

# Erste Anfrage
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

# Antwort enthält: "has_more": true, "next_page": "page_xyz..."

# Nächste Anfrage mit Paginierung
curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Häufige Anwendungsfälle

Erkunde detaillierte Implementierungen im Claude Cookbook:

• Tägliche Nutzungsberichte: Verfolge Trends im Token-Verbrauch
• Kostenzuordnung: Ordne Ausgaben nach Workspace für Chargebacks zu
• Cache-Effizienz: Miss und optimiere Prompt-Caching
• Budget-Monitoring: Richte Alerts für Ausgabenschwellen ein
• CSV-Export: Generiere Berichte für Finanzteams



Häufig gestellte Fragen



Wie aktuell sind die Daten?

Nutzungs- und Kostendaten erscheinen in der Regel innerhalb von 5 Minuten nach Abschluss der API-Anfrage, wobei Verzögerungen gelegentlich länger sein können.



Was ist die empfohlene Polling-Frequenz?

Die API unterstützt Polling einmal pro Minute für dauerhafte Nutzung. Für kurze Bursts (z. B. Herunterladen paginierter Daten) ist häufigeres Polling akzeptabel. Cache die Ergebnisse für Dashboards, die häufige Updates benötigen.



Wie verfolge ich die Nutzung der Code-Ausführung?

Kosten für Code-Ausführung erscheinen im Cost-Endpunkt gruppiert unter Code Execution Usage im Description-Feld. Code-Ausführung ist nicht im Usage-Endpunkt enthalten.



Wie verfolge ich die Priority-Tier-Nutzung?

Filtere oder gruppiere nach service_tier im Usage-Endpunkt und suche nach dem Wert priority. Priority-Tier-Kosten sind im Cost-Endpunkt nicht verfügbar.



Was passiert mit der Workbench-Nutzung?

API-Nutzung aus der Workbench ist keinem API-Key zugeordnet, daher ist api_key_id null, auch wenn nach dieser Dimension gruppiert wird.



Wie wird der Standard-Workspace dargestellt?

Nutzung und Kosten, die dem Standard-Workspace zugeordnet sind, haben einen null-Wert für workspace_id.



Wie erhalte ich Kostenaufschlüsselungen pro Benutzer für Claude Code?

Verwende die Claude Code Analytics API, die geschätzte Kosten pro Benutzer und Produktivitätsmetriken bereitstellt, ohne die Performance-Einschränkungen beim Aufschlüsseln von Kosten nach vielen API-Keys. Für allgemeine API-Nutzung mit vielen Keys verwende die Usage API, um den Token-Verbrauch als Kosten-Proxy zu verfolgen.



Siehe auch

Die Usage- und Cost-APIs können dir helfen, deinen Nutzern ein besseres Erlebnis zu bieten, Kosten zu verwalten und dein Ratenlimit zu schonen. Erfahre mehr über einige dieser weiteren Features:

• Admin API
• Admin-API-Referenz
• Analytics APIs – Welche Analytics-API und welchen Key-Typ deine Organisation benötigt
• Preise
• Prompt-Caching – Optimiere Kosten mit Caching
• Batch-Verarbeitung – 50 % Rabatt auf Batch-Anfragen
• Ratenlimits – Verstehe Nutzungsstufen
• Rate Limits API – Lies deine konfigurierten Ratenlimits aus
• Data Residency – Steuere die Inferenz-Geografie