Usage and Cost API

La Usage & Cost Admin API fornisce accesso programmatico e granulare ai dati storici di utilizzo e costo dell'API per la tua organizzazione. Questi dati sono simili alle informazioni disponibili nelle pagine Usage e Cost della Claude Console.

Questa API ti consente di monitorare, analizzare e ottimizzare meglio le tue implementazioni di Claude:

• Tracciamento accurato dell'utilizzo: Ottieni conteggi precisi dei token e pattern di utilizzo invece di affidarti esclusivamente al conteggio dei token di risposta
• Riconciliazione dei costi: Abbina i record interni con la fatturazione di Anthropic per i team finanziari e contabili
• Prestazioni e miglioramento del prodotto: Monitora le prestazioni del prodotto misurando se le modifiche al sistema lo hanno migliorato, oppure imposta avvisi
• Ottimizzazione dei limiti di velocità: Ottimizza funzionalità come la cache dei prompt o prompt specifici per sfruttare al meglio la capacità allocata.
• Analisi avanzata: Esegui analisi dei dati più approfondite rispetto a quanto disponibile nella Console

Le organizzazioni Claude Enterprise utilizzano invece una chiave API Analytics con un'API diversa; consulta Quale API ti serve?.

Quale API ti serve?

Anthropic fornisce report di costo e utilizzo tramite due API, a seconda di quale prodotto Claude gestisce la tua organizzazione:

Le organizzazioni principali Claude Enterprise non appaiono nella Claude Console e non dispongono di Admin API key, quindi per esse la chiave API Analytics è l'unico modo per accedere a questi dati. Consulta Analytics APIs per sapere come creare ciascun tipo di chiave e a quali piani si applicano i dati di costo di Claude Enterprise.

Soluzioni partner

Le principali piattaforme di osservabilità offrono integrazioni pronte all'uso per monitorare l'utilizzo e il costo della tua API Claude, senza scrivere codice personalizzato. Queste integrazioni forniscono dashboard, avvisi e analisi per aiutarti a gestire efficacemente l'utilizzo della tua API.

Avvio rapido

Ottieni l'utilizzo giornaliero della tua organizzazione per gli ultimi 7 giorni:

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Usage API

Traccia il consumo di token nella tua organizzazione con suddivisioni dettagliate per modello, workspace e service tier con l'endpoint /v1/organizations/usage_report/messages.

Concetti chiave

• Time bucket: Aggrega i dati di utilizzo in intervalli fissi (1m, 1h o 1d)
• Tracciamento dei token: Misura i token di input non memorizzati in cache, di input memorizzati in cache, di creazione della cache e di output
• Filtraggio e raggruppamento: Filtra per API key, workspace, modello, service tier, finestra di contesto, data residency o velocità (beta), e raggruppa i risultati per queste dimensioni
• Utilizzo degli strumenti server: Traccia l'uso degli strumenti lato server come la ricerca web

Per i dettagli completi dei parametri e gli schemi di risposta, consulta il riferimento della Usage API.

Esempi di base

Utilizzo giornaliero per modello

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Utilizzo orario con filtraggio

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-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Filtra l'utilizzo per API key e workspace

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Data residency

Traccia i tuoi controlli di data residency raggruppando e filtrando l'utilizzo con la dimensione inference_geo. Questo è utile per verificare il routing geografico nella tua organizzazione.

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Puoi anche filtrare per una geo specifica. I valori validi sono global, us e 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Fast mode (research preview)

Traccia l'utilizzo della fast mode raggruppando e filtrando con la dimensione speed. Questo è utile per monitorare l'utilizzo della modalità standard rispetto a quella 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&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Puoi anche filtrare per una velocità specifica. I valori validi sono standard e 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" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Limiti di granularità temporale

Cost API

Recupera suddivisioni dei costi a livello di servizio in USD con l'endpoint /v1/organizations/cost_report.

Concetti chiave

• Valuta: Tutti i costi in USD, riportati come stringhe decimali nelle unità più basse (centesimi)
• Tipi di costo: Traccia i costi di utilizzo dei token, ricerca web ed esecuzione di codice
• Raggruppamento: Raggruppa i costi per workspace o descrizione per suddivisioni dettagliate. Quando si raggruppa per description, le risposte includono campi analizzati come model e inference_geo
• Time bucket: Solo granularità giornaliera (1d)

Per i dettagli completi dei parametri e gli schemi di risposta, consulta il riferimento della Cost API.

Esempio di base

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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Paginazione

Entrambi gli endpoint supportano la paginazione per dataset di grandi dimensioni:

1. Effettua la tua richiesta iniziale.
2. Se has_more è true, usa il valore next_page nella tua richiesta successiva.
3. Continua finché has_more non è false.

# Prima richiesta
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" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

# La risposta include: "has_more": true, "next_page": "page_xyz..."

# Richiesta successiva con paginazione
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..." \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Casi d'uso comuni

Esplora implementazioni dettagliate nel Claude Cookbook:

• Report di utilizzo giornaliero: Traccia le tendenze del consumo di token
• Attribuzione dei costi: Alloca le spese per workspace per i chargeback
• Efficienza della cache: Misura e ottimizza la cache dei prompt
• Monitoraggio del budget: Imposta avvisi per le soglie di spesa
• Esportazione CSV: Genera report per i team finanziari

Domande frequenti

Quanto sono aggiornati i dati?

I dati di utilizzo e costo appaiono tipicamente entro 5 minuti dal completamento della richiesta API, anche se i ritardi possono occasionalmente essere più lunghi.

Qual è la frequenza di polling consigliata?

L'API supporta il polling una volta al minuto per un uso prolungato. Per brevi raffiche (ad esempio, il download di dati paginati), è accettabile un polling più frequente. Memorizza nella cache i risultati per le dashboard che necessitano di aggiornamenti frequenti.

Come traccio l'utilizzo dell'esecuzione di codice?

I costi di esecuzione di codice appaiono nell'endpoint dei costi raggruppati sotto Code Execution Usage nel campo descrizione. L'esecuzione di codice non è inclusa nell'endpoint di utilizzo.

Come traccio l'utilizzo del Priority Tier?

Filtra o raggruppa per service_tier nell'endpoint di utilizzo e cerca il valore priority. I costi del Priority Tier non sono disponibili nell'endpoint dei costi.

Cosa succede con l'utilizzo del playground?

L'utilizzo dell'API dal playground nella Claude Console (e dal precedente Workbench prima di esso) non è associato a una API key, quindi api_key_id sarà null anche quando si raggruppa per quella dimensione.

Come è rappresentato il workspace predefinito?

L'utilizzo e i costi attribuiti al workspace predefinito hanno un valore null per workspace_id.

Come ottengo suddivisioni dei costi per utente per Claude Code?

Usa la Claude Code Analytics API, che fornisce costi stimati per utente e metriche di produttività senza le limitazioni di prestazioni derivanti dalla suddivisione dei costi per molte API key. Per l'utilizzo generale dell'API con molte chiavi, usa la Usage API per tracciare il consumo di token come proxy dei costi.

Vedi anche

Usa le Usage and Cost API per offrire un'esperienza migliore ai tuoi utenti, gestire i costi e preservare il tuo limite di velocità. Scopri di più su alcune di queste altre funzionalità:

• Admin API
• Riferimento Admin API
• Analytics APIs - Quale API analytics e tipo di chiave serve alla tua organizzazione
• Prezzi
• Cache dei prompt - Ottimizza i costi con la cache
• Elaborazione batch - Sconto del 50% sulle richieste batch
• Limiti di velocità - Comprendi i tier di utilizzo
• Rate Limits API - Leggi i tuoi limiti di velocità configurati
• Data residency - Controlla la geografia dell'inferenza