API Usage and Cost Analytics
Interroga l’utilizzo dei token e i costi della tua organizzazione Claude Console o Claude Enterprise per modello, workspace, chiave API, attore e altro ancora.
L’API Usage and Cost Analytics riporta l’utilizzo storico dei token e i costi della tua organizzazione, suddivisi in base alle dimensioni che scegli, come modello, workspace, chiave API o l’utente o l’account di servizio dietro ogni richiesta. Per le organizzazioni Claude Console, questi dati sono simili a quelli mostrati nelle pagine Utilizzo e Costo della Claude Console.
L’API ha due endpoint:
GET /v1/organizations/analytics/usageriporta il numero di token e il numero di richieste.GET /v1/organizations/analytics/costriporta i costi in USD.
L’API Usage and Cost Analytics è in beta. Invia l’header anthropic-beta: analytics-usage-cost-2026-08-24 e un header anthropic-version in ogni richiesta. L’SDK e la CLI ant inviano entrambi gli header per te e recuperano le pagine rimanenti mentre leggi i risultati, quindi limit imposta solo la dimensione della pagina.
Usa questa API per:
- Attribuire la spesa: suddividi il costo e l’utilizzo dei token per workspace, chiave API, modello, livello di servizio o identità che ha effettuato ciascuna richiesta.
- Trovare i maggiori consumatori: ordina i risultati per token, richieste o costo per rispondere a domande come “quali chiavi API spendono di più questo mese?”
- Costruire serie temporali: suddividi i risultati in intervalli giornalieri, orari o al minuto per dashboard e report finanziari.
- Integrare una sola volta: gli stessi endpoint, parametri e campi di risposta servono le organizzazioni Claude Console e Claude Enterprise.
Avvio rapido
Ottieni l’utilizzo giornaliero dei token per la prima settimana di settembre, con una riga per ciascun modello e giorno:
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.usage.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-09-08T00:00:00Z",
time_bucket_width="1d",
group_by=["model"],
limit=10,
)
for row in rows:
print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")La risposta contiene una riga per ciascun modello e giorno con utilizzo, a partire dal valore di total_tokens più alto. Questo esempio mostra una singola riga:
{
"data": [
{
"starting_at": "2026-09-03T00:00:00Z",
"ending_at": "2026-09-04T00:00:00Z",
"group": {
"product": null,
"model": "claude-sonnet-5",
"context_window": null,
"inference_geo": null,
"speed": null,
"slack_channel_id": null,
"claude_tag_category": null,
"claude_tag_user_id": null,
"rbac_group_id": null,
"workspace_id": null,
"service_tier": null,
"user_profile_id": null,
"agent_id": null,
"environment_id": null,
"deployment_id": null,
"session_id": null,
"actor": null,
"actor_type": null,
"api_key_id": null
},
"usage": {
"uncached_input_tokens": 1284500,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 215300
},
"cache_read_input_tokens": 3200000,
"output_tokens": 891000,
"total_tokens": 5590800,
"server_tool_use": {
"web_search_requests": 12
},
"requests": 4210
}
}
],
"has_more": true,
"next_page": "page_V2mQ4dkt9HcbX3pLr...",
"data_refreshed_at": "2026-09-18T16:02:11Z"
}Come sono strutturati i risultati
- Ogni riga ha tre parti:
starting_ateending_atindicano il periodo coperto dalla riga,groupcontiene ogni dimensione eusage(ocostnell’endpoint dei costi) contiene le metriche. - Le dimensioni sono null se non raggruppate: una dimensione in
groupènulla meno che tu non la elenchi ingroup_by[]. Una dimensione raggruppata ènullanche nelle righe che non hanno un valore per essa, comemodelnell’utilizzo dell’esecuzione di codice.group_by[]accetta fino a cinque dimensioni. - Una riga per ciascuna combinazione: ogni riga è una combinazione delle dimensioni raggruppate, e ogni combinazione con utilizzo o costo compare esattamente una volta tra le pagine di una query. Senza
group_by[]e senzatime_bucket_width, la risposta è una singola riga che totalizza l’intero intervallo. - Gli intervalli temporali sono facoltativi: imposta
time_bucket_widthsu1m,1ho1dper suddividere ciascuna combinazione per intervallo UTC;starting_ateending_atdi ogni riga corrispondono quindi ai limiti del relativo intervallo. Gli intervalli senza utilizzo o costo non producono righe. - Ordinate per classifica per impostazione predefinita: Le righe sono ordinate in base alla metrica
order_bysull’intero intervallo, dalla più grande per impostazione predefinita (order=ascinverte l’ordine). Per costruire una serie temporale, impostatime_bucket_widtheorder_by=time. Le righe vengono quindi restituite un intervallo temporale dopo l’altro, con l’intervallo più recente per primo per impostazione predefinita (order=ascmette per primo il più vecchio), e con le righe più grandi per prime all’interno di ogni intervallo. Riempi gli intervalli vuoti con zeri. - I filtri funzionano insieme al raggruppamento: la maggior parte delle dimensioni per cui puoi raggruppare ha un filtro a lista corrispondente in notazione con parentesi quadre, come
models[]=claude-opus-5-5. Ripeti il parametro per passare più valori, fino a 100. Più valori per lo stesso filtro sono combinati con OR, mentre filtri diversi sono combinati con AND. I filtri egroup_by[]sono indipendenti; puoi filtrare per qualsiasi dimensione con o senza raggrupparla, o viceversa.
Dimensioni come model e actor si applicano a ogni organizzazione. Alcune, come api_key_id, si applicano solo alle organizzazioni Claude Console, e altre, come slack_channel_id, si applicano solo alle organizzazioni Claude Enterprise. Una dimensione che non si applica alla tua organizzazione è null in ogni riga e il suo filtro non corrisponde a nulla; l’eccezione è rbac_group_id, che restituisce invece un errore quando i team non sono disponibili per la tua organizzazione. Il riferimento API per utilizzoAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) e costiAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) elenca ogni dimensione, filtro e valore.
Attori
La dimensione actor indica a chi è attribuita una richiesta: un utente, un account di servizio, un’identità cloud federata (un principal AWS o Google Cloud, per le organizzazioni che accedono a Claude tramite la propria piattaforma cloud) oppure, quando nessuno di questi è dietro la richiesta, la chiave API stessa. Quando raggruppi per actor, l’actor di ogni riga è un oggetto il cui type indica di che tipo si tratta. L’utilizzo che non può essere attribuito ad alcuna identità ha actor: null.
Le chiavi personali e le chiavi di account di servizio agiscono come l’utente o l’account di servizio a cui sono collegate, quindi le loro richieste mostrano quell’identità come actor e la chiave in api_key_id. Le chiavi di workspace legacy non sono collegate a un’identità, quindi la chiave compare sia come actor sia come api_key_id.
Le richieste effettuate senza una chiave API, ad esempio dalla Claude Console o con un token di Workload Identity Federation, hanno api_key_id: null. Con un token di Workload Identity Federation, l’actor è l’account di servizio per conto del quale agisce il token.
In qualunque modo un membro acceda a Claude Code con il proprio account della Claude Console, l’actor è quel membro. Se Claude Code crea una chiave API al momento dell’accesso, api_key_id è quella chiave, che si trova nel workspace di Claude Code. Dopo un accesso senza chiave API, api_key_id è null.
L’utilizzo di token di alcune sessioni di Claude Managed Agents viene attribuito a un account di servizio gestito da Anthropic (svac_...). Per questo utilizzo, api_key_id è null. L’account non è elencato insieme agli account di servizio che crei tu. Consulta Trovare l’utilizzo delle sessioni in tutta l’organizzazione.
I filtri api_key_ids[] e actor_ids[] rispondono a domande diverse. api_key_ids[]=apikey_... corrisponde a ogni richiesta autenticata dalla chiave, indipendentemente da a chi sia attribuita. actor_ids[]=apikey_... corrisponde solo alle richieste attribuite alla chiave stessa. Per includere l’utilizzo senza chiave API in un filtro api_key_ids[], aggiungi una voce vuota: api_key_ids[]=.
Endpoint di utilizzo
GET /v1/organizations/analytics/usage restituisce i conteggi dei token per tipo. order_by accetta total_tokens (il valore predefinito), output_tokens, uncached_input_tokens, requests o time.
Ad esempio, per vedere una settimana di utilizzo per un workspace e una chiave API, suddivisa per livello di servizio (una riga per ciascun livello, che copre l’intera settimana):
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.usage.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-09-08T00:00:00Z",
workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
group_by=["service_tier"],
)
for row in rows:
print(f"{row.group.service_tier}: {row.usage.total_tokens}")Per cercare gli ID delle chiavi API e dei workspace, usa gli endpoint Elenca le chiavi APIAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) e Elenca i workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) oppure la Claude Console.
Per trovare quali utenti, account di servizio e chiavi API hanno effettuato più richieste in un mese:
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.usage.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-10-01T00:00:00Z",
group_by=["actor"],
order_by="requests",
limit=25,
)
for row in rows:
print(f"{row.group.actor}: {row.usage.requests}")Endpoint dei costi
GET /v1/organizations/analytics/cost accetta gli stessi filtri, dimensioni e intervalli temporali dell’endpoint /usage. L’oggetto cost di ogni riga contiene amount (il costo dopo gli sconti e prima dell’applicazione di eventuali crediti), list_amount (il costo a prezzi di listino), currency (sempre "USD") e requests. Gli importi sono stringhe decimali in centesimi con sei cifre decimali: "41280.000000" corrisponde a $412,80 USD. order_by accetta amount (il valore predefinito), list_amount o time.
Due dimensioni aggiuntive esistono solo in questo endpoint e non contano ai fini del limite di cinque dimensioni: group_by[]=cost_type suddivide ogni riga in una riga per ciascun tipo di costo, e group_by[]=token_type suddivide il costo dei token in una riga per ciascun tipo di token. Nemmeno limit si applica a queste due dimensioni, quindi una pagina può contenere più di limit righe. Ad esempio, il costo per modello, tipo di costo e tipo di token per un mese:
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.cost.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-10-01T00:00:00Z",
group_by=["model", "cost_type", "token_type"],
)
for row in rows:
print(
f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
)Per ciascun modello, la risposta contiene cinque righe tokens (una per ciascun tipo di token) più una riga ciascuna per web_search, code_execution e session_usage. Una di queste righe:
{
"starting_at": "2026-09-01T00:00:00Z",
"ending_at": "2026-10-01T00:00:00Z",
"group": {
"model": "claude-opus-5",
...,
"cost_type": "tokens",
"token_type": "cache_read_input_tokens"
},
"cost": {
"currency": "USD",
"amount": "41280.000000",
"list_amount": "51600.000000",
"requests": null
}
}L’oggetto group contiene tutte le dimensioni ed è abbreviato qui. Quando è specificato group_by[]=cost_type o token_type, requests è null in ogni riga.
Intervalli di date e intervalli temporali
- I timestamp sono in formato RFC 3339 con un offset UTC, ad esempio
2026-09-01T00:00:00Z.starting_atè inclusivo eending_atè esclusivo. starting_atdeve essere uguale o successivo al 1° gennaio 2026 e compreso negli ultimi 365 giorni. Una richiesta può coprire al massimo 31 giorni; per impostazione predefinita,ending_atcorrisponde a 31 giorni dopostarting_ato all’ora corrente, a seconda di quale sia precedente.ending_atè obbligatorio ogni volta che è impostatotime_bucket_width, e contime_bucket_width=1muna richiesta può coprire al massimo 24 ore.- Entrambi gli estremi dell’intervallo vengono arrotondati per difetto al limite di un intervallo UTC, o all’ora quando
time_bucket_widthnon è impostato. Ad esempio, contime_bucket_width=1h, unostarting_atdi2026-09-01T10:43:00Zviene trattato come2026-09-01T10:00:00Ze unending_atdi2026-09-01T15:43:00Zcome2026-09-01T15:00:00Z, quindi la risposta copre dalle 10:00 alle 15:00 UTC.
Aggiornamento dei dati
Ogni risposta include un timestamp data_refreshed_at, e l’utilizzo successivo a quel momento è mancante o parziale. Quando non sono ancora disponibili dati per nessuna parte dell’intervallo richiesto, data_refreshed_at è null e data è vuoto. I dati vengono in genere aggiornati entro 4 ore dall’utilizzo sottostante e possono richiedere fino a 24 ore. I valori possono essere rivisti man mano che arrivano eventi in ritardo e vengono eseguite le riconciliazioni, fino a circa 7 giorni dopo la fine del mese solare. Ad esempio, i valori del 1° ottobre possono cambiare fino a circa il 7 novembre. Per ottenere risultati stabili tra chiamate ripetute, imposta ending_at a un valore uguale o precedente a un data_refreshed_at che hai già visto; per i totali definitivi, interroga solo i mesi terminati da almeno 7 giorni. Ogni pagina di una query paginata legge la stessa istantanea dei dati, quindi data_refreshed_at è identico tra le pagine.
Migrare dall’API Usage and Cost
Questa sezione è rivolta alle organizzazioni Claude Console che chiamano l’API Usage and Cost legacy (/v1/organizations/usage_report/messages e /v1/organizations/cost_report). La tua chiave Admin API, l’header anthropic-version, starting_at e ending_at, i valori di ampiezza degli intervalli (1m, 1h, 1d), la notazione con parentesi quadre, i nomi dei campi di paginazione e i nomi dei campi di token e costo restano invariati. Cosa cambia:
| API Usage and Cost | API Usage and Cost Analytics |
|---|---|
| Nessun header beta | anthropic-beta: analytics-usage-cost-2026-08-24 in ogni richiesta |
| I dati compaiono in genere entro 5 minuti | I dati vengono in genere aggiornati entro 4 ore e possono richiedere fino a 24 ore (vedi Aggiornamento dei dati) |
data è una lista di intervalli temporali, dal più vecchio, inclusi quelli vuoti, ciascuno con una lista results le cui voci contengono dimensioni e metriche affiancate | data è una lista di righe ordinate per order_by, ciascuna con i propri starting_at e ending_at, le dimensioni in group e le metriche in usage o cost. Le combinazioni senza utilizzo o costo non hanno righe. |
bucket_width, predefinito 1d | time_bucket_width, nessun valore predefinito. Passa time_bucket_width=1d per mantenere le righe giornaliere; omettilo per i totali sull’intero intervallo. L’endpoint dei costi accetta anche tutti i filtri e gli intervalli 1m e 1h. |
limit conta gli intervalli temporali per pagina | limit conta le righe per pagina (da 1 a 1.000, predefinito 20), quindi il numero di pagine dipende da quante combinazioni hanno dati |
| Qualsiasi intervallo di date, paginato in avanti per intervallo | starting_at a partire dal 1° gennaio 2026 ed entro gli ultimi 365 giorni, al massimo 31 giorni per richiesta, ending_at obbligatorio con time_bucket_width e al massimo 24 ore con intervalli 1m (vedi Intervalli di date e intervalli temporali). Suddividi gli intervalli più lunghi in più richieste. |
account_ids[], service_account_ids[], group_by[]=account_id, group_by[]=service_account_id | actor_ids[] con gli stessi ID con prefisso, e group_by[]=actor o actor_type; leggi actor.user_id o actor.service_account_id. Vedi Attori. |
context_window[] | context_windows[] |
group_by[]=description nel report dei costi, con una stringa description | Nessun description. Raggruppa invece per le dimensioni strutturate: qualsiasi tra model, cost_type, token_type, context_window, service_tier, inference_geo e speed, che rientrano tutte in una sola richiesta. |
| Un ID di chiave API o di workspace sconosciuto restituisce un errore | Non corrisponde a nulla, incluso un nome models[] scritto in modo errato. Ogni lista accetta fino a 100 valori. |
workspace_id: null per il workspace predefinito | Il workspace_id reale del workspace predefinito (vedi Come viene rappresentato il workspace predefinito?) |
inference_geo: "not_available" e service_tier: "standard" sull’utilizzo senza area geografica o livello | null per entrambi. inference_geos[]=not_available corrisponde comunque alle righe senza area geografica di inferenza. |
Il service_tier dei costi è standard o batch; amount come "123.45" | Il livello effettivo; amount con sei cifre decimali, come "123.450000", più list_amount. |
| Esecuzione di codice non presente nel report di utilizzo; nessun conteggio delle richieste | L’esecuzione di codice compare come righe di utilizzo con model: null; aggiunge requests in entrambi gli endpoint e total_tokens nelle righe di utilizzo |
Per riprodurre il report giornaliero legacy, richiedi time_bucket_width=1d con lo stesso group_by[], scorri le pagine con limit=1000, quindi raggruppa le righe per starting_at e riempi i giorni mancanti con zeri. Aggiungi order_by=time&order=asc per ottenere i giorni in ordine. Utilizzo giornaliero per modello per 1 settimana, prima:
curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
-H "anthropic-version: 2026-10-21" \
-H "x-api-key: $ANTHROPIC_API_KEY"e dopo:
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.usage.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-09-08T00:00:00Z",
time_bucket_width="1d",
group_by=["model"],
limit=1000,
)
for row in rows:
print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")Costo giornaliero per workspace, modello, livello di servizio, finestra di contesto e area geografica di inferenza, suddiviso per tipo di costo e tipo di token:
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.cost.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-09-08T00:00:00Z",
time_bucket_width="1d",
group_by=[
"workspace_id",
"model",
"service_tier",
"context_window",
"inference_geo",
"cost_type",
"token_type",
],
limit=1000,
)
for row in rows:
group = row.group
print(
f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
f"{row.cost.amount}"
)Migrare dai report di utilizzo e costo di Claude Enterprise
Questa sezione è rivolta alle organizzazioni Claude Enterprise che chiamano gli endpoint di report della Claude Enterprise Analytics API usage_report, cost_report, user_usage_report e user_cost_report sotto /v1/organizations/analytics/. Questi endpoint sono legacy e restano supportati. Passa a /analytics/usage e /analytics/cost quando desideri una delle seguenti funzionalità:
- Ogni gruppo in ogni intervallo temporale, anziché i primi 100 gruppi di ciascun intervallo
- Raggruppamento per
actoroactor_typeinsieme ad altre dimensioni, sia per l’utilizzo sia per i costi - Righe ordinate in base a una metrica a tua scelta sull’intero intervallo, oppure ordinate per intervallo temporale
- Un’unica integrazione che serve anche le organizzazioni Claude Console
La tua chiave, la data più remota, il periodo di 365 giorni a ritroso e l’arco di 31 giorni, i nomi e i valori dei filtri e delle dimensioni (eccetto user_ids[] e il valore di prodotto Claude Tag), i campi actor dell’utente, i campi delle metriche e degli importi, data_refreshed_at, le regole del cursore e il limite di velocità a livello di organizzazione restano invariati. L’unico nuovo header è l’header beta analytics-usage-cost-2026-08-24. Cosa cambia:
| Report di Claude Enterprise | API Usage and Cost Analytics |
|---|---|
usage_report e cost_report restituiscono intervalli temporali, dal più vecchio, inclusi quelli vuoti, ciascuno contenente al massimo i suoi primi 100 gruppi; bucket_width è predefinito a 1d e limit conta gli intervalli | Righe che coprono ogni combinazione con dati, ordinate per order_by, ciascuna con i propri starting_at e ending_at, le dimensioni in group e le metriche in usage o cost. time_bucket_width è facoltativo e limit conta le righe. |
Il parametro dell’intervallo temporale è bucket_width | È time_bucket_width, con gli stessi valori |
In usage_report e cost_report, ending_at è facoltativo con bucket_width e gli intervalli 1m possono coprire fino a 31 giorni | ending_at obbligatorio con time_bucket_width; gli intervalli 1m coprono al massimo 24 ore per richiesta |
user_usage_report e user_cost_report restituiscono una riga per utente | group_by[]=actor&actor_types[]=user_actor. Senza il filtro ottieni anche righe per identità non utente e una riga actor: null per l’utilizzo non attribuito. |
L’utilizzo di Claude Tag ha product: "claude-tag" | product: "claude_tag"; products[] accetta entrambe le grafie |
Un nome models[] non riconosciuto restituisce un errore 400 | Non corrisponde a nulla |
user_ids[] | actor_ids[] con gli stessi ID con prefisso user_... |
exclude_deleted_users nei report per utente | Richiede group_by[]=actor; senza di esso, la richiesta restituisce un errore 400. Esclude solo le righe il cui actor è un utente con deleted: true; le righe per altre identità e le righe con actor: null restano. |
Costo per utente per un mese, prima:
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.user_cost_report.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-10-01T00:00:00Z",
limit=100,
)
for row in rows:
print(f"{row.actor.user_id}: {row.amount}")e dopo, aggiungendo una suddivisione per prodotto:
client = anthropic.Anthropic()
rows = client.beta.organization.analytics.cost.list(
starting_at="2026-09-01T00:00:00Z",
ending_at="2026-10-01T00:00:00Z",
actor_types=["user_actor"],
group_by=["actor", "product"],
limit=100,
)
for row in rows:
actor = row.group.actor
if actor is not None and actor.type == "user_actor":
print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")Domande frequenti
Come viene rappresentato il workspace predefinito?
Il workspace predefinito di un’organizzazione Claude Console ha un proprio ID wrkspc_, come ogni altro workspace. Le righe del workspace predefinito hanno quell’ID in workspace_id, e puoi filtrare in base a esso con workspace_ids[]. Elenca i workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro) esclude il workspace predefinito a meno che tu non passi include_default=true. Per verificare se un workspace_id sconosciuto è il workspace predefinito, passalo a Ottieni workspaceAnteprima disponibile con link al riferimento API (premi Tab finché il focus non entra nella scheda, Esc per tornare indietro): il workspace predefinito restituisce "name": "Default".
Come ottengo il costo per utente per Claude Code?
Chiama l’endpoint dei costi con products[]=claude_code&group_by[]=actor. Le organizzazioni Claude Console possono anche usare l’API Claude Code Analytics, che riporta l’attività di Claude Code per utente e il costo stimato.
Vedi anche
- API Usage and Cost (legacy)
- API di analisi: quale API di analisi e quale tipo di chiave servono alla tua organizzazione
- API Claude Code Analytics
- Riferimento Admin API
- Prezzi
Questa pagina ti è stata utile?