API Usage and Cost Analytics

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 Usage e Cost della Claude Console.

L’API ha due endpoint:

• GET /v1/organizations/analytics/usage riporta il numero di token e il numero di richieste.
• GET /v1/organizations/analytics/cost riporta 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_at e ending_at indicano il periodo coperto dalla riga, group contiene ogni dimensione e usage (o cost nell’endpoint dei costi) contiene le metriche.
• Le dimensioni sono null se non raggruppate: una dimensione in group è null a meno che tu non la elenchi in group_by[]. Una dimensione raggruppata è null anche nelle righe che non hanno un valore per essa, come model nell’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 senza time_bucket_width, la risposta è una singola riga che totalizza l’intero intervallo.
• Gli intervalli temporali sono facoltativi: imposta time_bucket_width su 1m, 1h o 1d per suddividere ciascuna combinazione per intervallo UTC; starting_at e ending_at di 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_by sull’intero intervallo, dalla più grande per impostazione predefinita (order=asc inverte l’ordine). Per costruire una serie temporale, imposta time_bucket_width e order_by=time. Le righe vengono quindi restituite un intervallo temporale dopo l’altro, con l’intervallo più recente per primo per impostazione predefinita (order=asc mette 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 e group_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 utilizzo e costi 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 service account agiscono come l’utente o il service account 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. L’eccezione è la chiave che Claude Code crea quando un membro accede con il proprio account Claude Console: si trova nel workspace di Claude Code e il suo utilizzo è attribuito a quel membro. 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; l’actor di un workload federato è il suo account di servizio. Per includere l’utilizzo senza chiave API in un filtro api_key_ids[], aggiungi una voce vuota: api_key_ids[]=.

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.

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 List API Keys e List Workspaces 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 e ending_at è esclusivo.
• starting_at deve 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_at corrisponde a 31 giorni dopo starting_at o all’ora corrente, a seconda di quale sia precedente.
• ending_at è obbligatorio ogni volta che è impostato time_bucket_width, e con time_bucket_width=1m una 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_width non è impostato. Ad esempio, con time_bucket_width=1h, uno starting_at di 2026-09-01T10:43:00Z viene trattato come 2026-09-01T10:00:00Z e un ending_at di 2026-09-01T15:43:00Z come 2026-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:

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: 2023-06-01" \
  -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 actor o actor_type insieme 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:

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[]. List Workspaces 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 Get Workspace: 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 la Claude Code Analytics API, 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
• Claude Code Analytics API
• Riferimento Admin API
• Prezzi