API di utilizzo e costo

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 di amministrazione per utilizzo e costo 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 Utilizzo e Costo 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 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 del limite di velocità e del livello di priorità: Ottimizza funzionalità come la memorizzazione nella cache dei prompt o prompt specifici per sfruttare al massimo la capacità allocata, o acquista capacità dedicata.
Analisi avanzata: Esegui analisi dei dati più approfondite rispetto a quelle disponibili in Console

Chiave API di amministrazione richiesta

Questa API fa parte dell'API di amministrazione. Questi endpoint richiedono una chiave API di amministrazione (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 di amministrazione 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 l'utilizzo dell'API in modo efficace.

CloudZero

Piattaforma di intelligenza cloud 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)

API di utilizzo

Traccia il consumo di token in tutta la 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 memorizzati nella cache, input memorizzati nella cache, creazione della cache e token di output
Filtro e raggruppamento: 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
Utilizzo di strumenti server: Traccia l'utilizzo di strumenti lato server come la ricerca web

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

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 filtro

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-7&\
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 Elenca chiavi API.

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

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.

Modalità veloce (beta: anteprima di ricerca)

Traccia l'utilizzo della modalità veloce raggruppando e filtrando con la dimensione speed. Questo è utile per monitorare l'utilizzo della 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ADMIN_API_KEY"

Puoi anche filtrare a 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" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: fast-mode-2026-02-01" \
  --header "x-api-key: $ADMIN_API_KEY"

Sia il filtro speeds[] che il valore speed group_by richiedono l'header beta fast-mode-2026-02-01.

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

API di costo

Recupera suddivisioni di costo 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 raggruppi 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 di risposta, consulta il riferimento dell'API di costo.

I costi del livello di priorità utilizzano un modello di fatturazione diverso e non sono inclusi nell'endpoint di costo. Traccia l'utilizzo del livello di priorità 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 richiesta successiva
Continua fino a quando has_more è 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..."

# 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..." \
  --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 addebiti
Efficienza della cache: Misura e ottimizza la memorizzazione nella cache dei prompt
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 esempio, il download di dati paginati), il polling più frequente è accettabile. Memorizza nella cache i risultati per i dashboard che richiedono aggiornamenti frequenti.

Come tracciare l'utilizzo dell'esecuzione del codice?

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

Come tracciare l'utilizzo del livello di priorità?

Filtra o raggruppa per service_tier nell'endpoint di utilizzo e cerca il valore priority. I costi del livello di priorità non sono disponibili nell'endpoint di costo.

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 di costo per utente per Claude Code?

Utilizza l'API di analitiche di Claude Code, 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 di utilizzo per tracciare il consumo di token come proxy di costo.

Vedi anche

Le API di utilizzo e costo 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'API di amministrazione
Riferimento dell'API di amministrazione
Prezzi
Memorizzazione nella cache dei prompt - Ottimizza i costi con la memorizzazione nella cache
Elaborazione batch - Sconto del 50% sulle richieste batch
Limiti di velocità - Comprendi i livelli di utilizzo
Residenza dei dati - Controlla la geografia dell'inferenza