Costi API Claude: una nuova API mostra chi spende token e per cosa

Il 29 ottobre Anthropic ha rilasciato in beta la Usage and Cost Analytics API, una nuova API per monitorare il consumo di token e i costi API Claude all’interno di un’organizzazione. Secondo le Claude Release Notes, da quel giorno la vecchia Usage and Cost API diventa un’API “legacy”, anche se resta supportata.

Cosa cambia nei report sui costi API Claude?

L’API ha due endpoint:

1. GET /v1/organizations/analytics/usage restituisce il numero di token e di richieste,
2. GET /v1/organizations/analytics/cost restituisce il costo in USD.

La parte più interessante è come possiamo suddividere questi dati. In una sola richiesta raggruppiamo i risultati per un massimo di cinque dimensioni: modello, workspace, chiave API, tier di servizio, finestra di contesto, regione di inferenza, prodotto e il cosiddetto “attore”, cioè chi ha effettivamente inviato la richiesta. L’attore può essere un utente, un account di servizio, un’identità di AWS o di Google Cloud oppure, se non c’è nessuno di questi, la chiave API stessa.

I risultati arrivano sotto forma di classifica, ordinata di default dal consumo più alto. La domanda “quali chiavi API hanno speso di più questo mese?” diventa quindi una sola richiesta, non uno script che mette insieme dati da più report.

Per Claude Code c’è una ricetta pronta: il costo per utente si ottiene con una richiesta con products[]=claude_code&group_by[]=actor. Dopo le misurazioni secondo cui i riepiloghi nascosti degli agenti si mangiano il 16–22% dei costi di una sessione, arriva proprio al momento giusto.

Com’è fatta una richiesta?

Un esempio dalla documentazione: il consumo giornaliero di token nella prima settimana di settembre, separato per modello.

curl --globoff "https://api.anthropic.com/v1/organizations/analytics/usage?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
time_bucket_width=1d&\
group_by[]=model&\
limit=10" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: analytics-usage-cost-2026-08-24" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

Ogni riga ha tre parti: l’intervallo di tempo, group con le dimensioni e usage (o cost) con i numeri. In usage troviamo, tra l’altro, i token di input senza cache, i token scritti e letti dalla cache, i token di output, il numero di ricerche web e il numero di richieste. Lo stesso è disponibile tramite l’SDK e la CLI ant (ant beta:organization:analytics:usage list).

Qualche dettaglio:

1. Gli intervalli di tempo sono di 1 minuto, 1 ora o 1 giorno, tutto in UTC.
2. Una richiesta copre al massimo 31 giorni, e con intervalli di un minuto solo 24 ore.
3. I dati risalgono fino al 1° gennaio 2026 e al massimo a 365 giorni prima.
4. Una pagina di risultati ha da 1 a 1000 righe (20 di default).

Cosa mostra l’endpoint dei costi?

L’endpoint /cost restituisce due importi: amount, cioè il costo dopo gli sconti ma prima di scalare i crediti, e list_amount, cioè il costo a prezzi di listino. Gli importi sono espressi in centesimi con sei cifre decimali, quindi "41280.000000" significa 412,80 USD.

Due dimensioni aggiuntive, cost_type e token_type, suddividono il costo per tipo di token, ricerca web, esecuzione di codice e sessioni. Non contano nel limite delle cinque dimensioni.

A cosa fare attenzione?

Primo, al ritardo. I dati si aggiornano di solito entro 4 ore, a volte fino a 24 ore, mentre nella vecchia Usage and Cost API comparivano di solito entro 5 minuti. Per gli alert “qui e ora” conviene quindi cercare altro.

Secondo, alle rettifiche. I valori possono cambiare ancora per circa 7 giorni dopo la fine del mese solare, quindi i totali definitivi di ottobre li avremo intorno al 7 novembre.

Terzo, al Priority Tier. Le richieste fatte nell’ambito di un Priority Tier acquistato compaiono nel consumo, ma il loro costo in token è zero, perché l’impegno si paga a parte.

Quarto, all’accesso. L’API funziona solo per le organizzazioni: nella Claude Console con una chiave Admin API e in Claude Enterprise con una chiave con il permesso read:analytics. Gli account individuali non possono usarla. Funziona anche su Claude Platform on AWS e in Claude Models on Google Cloud, con l’autenticazione del rispettivo cloud.

È una novità nel mondo dell’IA?

I report sui costi nella Claude Console esistevano già. La novità è che gli stessi endpoint e campi servono sia le organizzazioni nella Claude Console sia Claude Enterprise. Per Enterprise sparisce anche un limite: i vecchi report restituivano solo i 100 gruppi più grandi per ogni intervallo, quelli nuovi li restituiscono tutti.

È un altro passo di Anthropic verso il controllo della spesa, subito dopo i Claude smart reports, che mostrano cosa ha fatto un team con Claude e quanto è costato.

FAQ

Come controllare i costi API Claude?

Nella Claude Console, nelle pagine Usage e Cost, oppure in modo programmatico con la Usage and Cost Analytics API (endpoint /v1/organizations/analytics/cost) e una chiave Admin API. Ogni singola risposta dell’API contiene anche un blocco usage con il numero di token di quella richiesta.

La vecchia Usage and Cost API smetterà di funzionare?

Al 29 ottobre no. Secondo le Claude Release Notes ha lo stato “legacy”, ma resta supportata, e la documentazione include una guida alla migrazione.

Come vedere quanto spende ogni utente di Claude Code?

Con l’endpoint dei costi e i parametri products[]=claude_code&group_by[]=actor. Le organizzazioni nella Claude Console possono usare anche la Claude Code Analytics API, che è separata.