Usage and Cost API

The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

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

Chiave API Admin richiesta

Questa API fa parte dell'Admin API. Questi endpoint richiedono una chiave API Admin (che inizia con sk-ant-admin...) che differisce dalle chiavi API standard. Solo i membri dell'organizzazione con il ruolo di amministratore possono fornire chiavi API Admin tramite la Claude 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.

CloudZero

Piattaforma di cloud intelligence per il tracciamento e la previsione dei costi

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"

Imposta un header User-Agent per le integrazioni

Se stai creando un'integrazione, imposta il tuo header User-Agent per aiutarci a comprendere i modelli di utilizzo:

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"

Per recuperare gli ID delle chiavi API della tua organizzazione, utilizza l'endpoint List API Keys.

Per recuperare gli ID dei workspace della tua organizzazione, utilizza l'endpoint List Workspaces, o trova gli ID dei workspace della tua organizzazione nella Anthropic Console.

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"

I modelli rilasciati prima di febbraio 2026 (prima di Claude Opus 4.6) non supportano il parametro di richiesta inference_geo, quindi i loro rapporti di utilizzo restituiscono "not_available" per questa dimensione. Puoi utilizzare not_available come valore di filtro in inference_geos[] per indirizzare quei modelli.

Limiti di granularità temporale

Granularità	Limite predefinito	Limite massimo	Caso d'uso
`1m`	60 bucket	1440 bucket	Monitoraggio in tempo reale
`1h`	24 bucket	168 bucket	Modelli giornalieri
`1d`	7 bucket	31 bucket	Rapporti settimanali/mensili

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.

I costi del Priority Tier utilizzano un modello di fatturazione diverso e non sono inclusi nell'endpoint dei costi. Traccia l'utilizzo del Priority Tier tramite l'endpoint di utilizzo.

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:

Effettua la tua richiesta iniziale
Se has_more è true, utilizza il valore next_page nella tua prossima richiesta
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