API di utilizzo e costi

La Usage & Cost Admin API fornisce accesso programmatico e granulare ai dati storici di utilizzo e costi 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 modelli di utilizzo invece di affidarti esclusivamente al conteggio dei token nelle risposte
• Riconciliazione dei costi: Abbina i registri interni con la fatturazione di Anthropic per i team di finanza e contabilità
• Prestazioni e miglioramento del prodotto: Monitora le prestazioni del prodotto misurando se le modifiche al sistema lo hanno migliorato, oppure configura avvisi
• Ottimizzazione del rate limit (limite di velocità): Ottimizza funzionalità come la cache dei prompt o prompt specifici per sfruttare al massimo 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 su costi e utilizzo tramite due API, a seconda di quale prodotto Claude gestisce la tua organizzazione:

Le organizzazioni padre di Claude Enterprise non compaiono nella Claude Console e non dispongono di chiavi Admin API, quindi per loro 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 dei partner

Le principali piattaforme di osservabilità offrono integrazioni pronte all'uso per monitorare l'utilizzo e i costi della tua API Claude, senza scrivere codice personalizzato. Queste integrazioni forniscono dashboard, avvisi e analisi per aiutarti a gestire efficacemente l'utilizzo dell'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"

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



Usage API

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



Concetti chiave

• Bucket temporali: Aggrega i dati di utilizzo in intervalli fissi (1m, 1h o 1d)
• Tracciamento dei token: Misura i token di input non in cache, input in cache, creazione della cache e output
• Filtri e raggruppamenti: Filtra per chiave API, workspace, modello, livello di servizio, finestra di contesto, residenza dei dati o velocità (beta), e raggruppa i risultati per queste dimensioni
• Uso degli strumenti lato server: Traccia l'uso degli strumenti lato server come la ricerca web

Per i dettagli completi dei parametri e gli schemi delle risposte, 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 filtri

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"



Filtrare l'utilizzo per chiavi API 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"



Residenza dei dati

Traccia i tuoi controlli di residenza dei dati raggruppando e filtrando l'utilizzo con la dimensione inference_geo. Questo è utile per verificare l'instradamento 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"



Modalità veloce (anteprima di ricerca)

Traccia l'utilizzo della modalità veloce raggruppando e filtrando con la dimensione speed. Questo è utile per monitorare l'utilizzo in modalità standard rispetto a quella veloce.

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 le 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ù piccole (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
• Bucket temporali: Solo granularità giornaliera (1d)

Per i dettagli completi dei parametri e gli schemi delle risposte, 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 richiesta iniziale.
2. Se has_more è true, usa il valore next_page nella 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 giornalieri: Traccia le tendenze di consumo dei token
• Attribuzione dei costi: Alloca le spese per workspace per i riaddebiti
• Efficienza della cache: Misura e ottimizza la cache dei prompt
• Monitoraggio del budget: Configura 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 costi compaiono in genere entro 5 minuti dal completamento della richiesta API, anche se occasionalmente i ritardi possono 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 del codice compaiono nell'endpoint dei costi raggruppati sotto Code Execution Usage nel campo description. 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 di Anthropic Workbench?

L'utilizzo dell'API dal Workbench non è associato a una chiave API, quindi api_key_id sarà null anche quando si raggruppa per quella dimensione.



Come viene rappresentato il workspace predefinito?

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



Come ottengo le 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 chiavi API. 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 di analytics e tipo di chiave servono 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 livelli di utilizzo
• Rate Limits API - Leggi i limiti di velocità configurati
• Residenza dei dati - Controlla la geografia dell'inferenza