Usage and Cost API

L'API Admin Usage & Cost 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 modelli di utilizzo invece di affidarti solo al conteggio dei token di risposta
• Riconciliazione dei costi: Abbina i record interni con la fatturazione di Anthropic per i team di finanza e contabilità
• Prestazioni e miglioramento del prodotto: Monitora le prestazioni del prodotto mentre misuri se i cambiamenti al sistema le hanno migliorate, o configura avvisi
• Ottimizzazione dei limiti di velocità e del Priority Tier: Ottimizza funzionalità come il prompt caching o prompt specifici per sfruttare al massimo la capacità allocata, o acquista capacità dedicata.
• Analisi avanzata: Esegui analisi dei dati più approfondite di quelle disponibili in Console

Soluzioni partner

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

Avvio rapido

Ottieni l'utilizzo giornaliero della tua organizzazione degli 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

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

Usage API

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

Concetti chiave

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

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

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

Filtra 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_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 il routing geografico in tutta la 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

Puoi anche filtrare a 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_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 del 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 buckets: Solo granularità giornaliera (1d)

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

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

Paginazione

Entrambi gli endpoint supportano la paginazione per set di dati di grandi dimensioni:

1. Effettua la tua richiesta iniziale
2. Se has_more è true, utilizza il valore next_page nella tua prossima richiesta
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" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

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

# Prossima richiesta 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..." \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ADMIN_API_KEY"

Casi d'uso comuni

Esplora implementazioni dettagliate in Claude Cookbook:

• Rapporti di utilizzo giornaliero: Traccia i trend di consumo dei token
• Attribuzione dei costi: Alloca le spese per workspace per chargeback
• Efficienza della cache: Misura e ottimizza il prompt caching
• Monitoraggio del budget: Configura avvisi per soglie di spesa
• Esportazione CSV: Genera rapporti per i team di finanza

Domande frequenti

Quanto sono freschi i dati?

I dati di utilizzo e costo in genere appaiono 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 l'uso sostenuto. Per brevi burst (ad es. download di dati paginati), il polling più frequente è accettabile. Memorizza nella cache i risultati per i dashboard che necessitano di aggiornamenti frequenti.

Come tracciare l'utilizzo dell'esecuzione del codice?

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

Come tracciare 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 Workbench?

L'utilizzo dell'API da Workbench non è associato a una chiave API, 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?

Utilizza l'API Claude Code Analytics, che fornisce costi stimati per utente e metriche di produttività senza i limiti di prestazioni della suddivisione dei costi per molte chiavi API. Per l'utilizzo generale dell'API con molte chiavi, utilizza l'API Usage per tracciare il consumo di token come proxy dei costi.

Vedi anche

Le API Usage e Cost possono essere utilizzate per aiutarti a fornire un'esperienza migliore ai tuoi utenti, aiutarti a gestire i costi e preservare il tuo limite di velocità. Scopri di più su alcune di queste altre funzionalità:

• Panoramica dell'Admin API
• Riferimento dell'Admin API
• Prezzi
• Prompt caching - Ottimizza i costi con il caching
• Elaborazione batch - Sconto del 50% sulle richieste batch
• Limiti di velocità - Comprendi i tier di utilizzo
• Residenza dei dati - Controlla la geografia dell'inferenza