Guida di riferimento dell'API Claude Enterprise Analytics

Panoramica

L'API Claude Enterprise Analytics fornisce alla tua organizzazione l'accesso programmatico ai dati di engagement, adozione, utilizzo e costi su tutte le superfici Claude all'interno della tua organizzazione Enterprise. Che tu stia creando dashboard interne per l'attività degli utenti, tracciando l'adozione di progetti, riconciliando le spese rispetto alla tua fattura mensile o impostando limiti di spesa, questa API fornisce le metriche di cui hai bisogno.

Aggregazione dei dati

Tutti i dati sono aggregati per organizzazione, per giorno. Ogni endpoint restituisce uno snapshot per una singola data che specifichi. I dati per il giorno (N-1) vengono elaborati alle 10:00:00 UTC nel giorno N e sono disponibili per le query tre giorni dopo l'aggregazione, per garantire l'accuratezza dei dati.

Se i dati non sono disponibili entro la timeline sopra indicata, questo di solito indica un errore della pipeline di dati che il nostro team dovrà investigare internamente. Di solito siamo consapevoli di tali problemi, ma ti preghiamo di segnalarlo al tuo CSM se desideri una verifica o sospetti qualcos'altro.

Gli endpoint di costo e utilizzo hanno un modello di freschezza diverso. Vedi Endpoint di costo e utilizzo di seguito per i dettagli.

Abilitazione dell'accesso

Per creare nuove chiavi API di analytics, devi essere un Primary Owner all'interno della tua organizzazione Enterprise. Puoi farlo navigando su claude.ai/analytics/api-keys.

Alcuni dettagli aggiuntivi che potrebbero essere utili:

Puoi abilitare/disabilitare l'accesso all'API pubblica in qualsiasi momento. Se disabiliti l'accesso attivando l'interruttore, tutte le richieste verranno negate.
Avrai bisogno di una chiave con l'ambito read:analytics per accedere all'API. Puoi creare più chiavi per la tua organizzazione, ma i limiti di velocità si applicano a livello di organizzazione, non a livello di chiave. Vedi la sezione "Rate limiting" di seguito.
Come sempre, ti consigliamo vivamente di gestire le chiavi API in modo sicuro: non condividere mai queste chiavi pubblicamente - sono segrete e devono essere condivise in modo sicuro.

URL di base

Tutte le richieste vengono inviate a:

https://api.anthropic.com/v1/organizations/analytics/

Autenticazione

Ogni richiesta richiede una chiave API passata nell'intestazione x-api-key. La tua chiave API deve avere l'ambito read:analytics. Puoi creare e gestire le chiavi API dalle impostazioni di amministrazione di claude.ai nella sezione Chiavi API.

Intestazioni di richiesta di esempio:

x-api-key: $YOUR_API_KEY

Paginazione

Diversi endpoint restituiscono risultati paginati. La paginazione utilizza un approccio basato su cursore, dove la risposta include un token next_page che passi di nuovo nella tua richiesta successiva per recuperare la pagina di risultati seguente.

Due parametri facoltativi controllano la paginazione:

limit (integer): Numero di record per pagina. Il valore predefinito è 20 per l'endpoint /users e 100 per tutti gli altri endpoint. Per gli endpoint di costo e utilizzo, i valori predefiniti variano in base all'endpoint e alla larghezza del bucket — vedi Endpoint di costo e utilizzo di seguito. Il massimo è 1000.

page (string): Il token cursore opaco dal campo next_page della risposta precedente. Ometti questo nella tua prima richiesta.

Quando non ci sono più risultati, next_page sarà null nella risposta.

Importante: Non modificare i parametri di query a metà sequenza sugli endpoint di costo e utilizzo. I cursori sono legati ai filtri e all'intervallo di date che li hanno emessi. Se modifichi products[], order_by, group_by[], l'intervallo di date o qualsiasi filtro e passi un cursore precedente, riceverai un errore 400.

Risposte di errore

Tutti gli endpoint restituiscono codici di errore HTTP standard:

Codice	Significato
400	Un parametro di query non è valido. Le cause comuni includono una data non valida, una data prima del 1/1/26 (prima disponibilità), una data che è oggi o nel futuro, o (sugli endpoint di costo e utilizzo) un cursore di pagina che non corrisponde ai parametri di query attuali.
401	Chiave API mancante o non valida (endpoint di costo e utilizzo).
404	La chiave API è mancante, non valida o non ha l'ambito `read:analytics`.
410	Il cursore di pagina non è più valido. Riavvia la paginazione dalla prima pagina.
429	Limite di velocità superato. Troppe richieste.
500	Errore interno (endpoint di costo e utilizzo).
504	Richiesta scaduta.

Rate limiting

Abbiamo limiti di velocità predefiniti in atto che si applicano a tutti gli endpoint in questa API. Se questo non è sufficiente per il tuo caso d'uso, ci piacerebbe capire perché. Se necessario, possiamo regolare i limiti di velocità per la tua organizzazione—contatta il tuo CSM.

Endpoint di engagement e adozione

1. Elenca attività utente

GET /v1/organizations/analytics/users

Restituisce metriche di engagement per utente per un singolo giorno. Ogni elemento nella risposta rappresenta un utente e include i conteggi della sua attività su Claude (chat) e Claude Code.

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`date`	stringa	Sì	La data per cui recuperare le metriche, nel formato YYYY-MM-DD.
`limit`	intero	No	Numero di record per pagina (predefinito: 20, massimo: 1000).
`page`	stringa	No	Token cursore dalla risposta precedente nel campo `next_page` per recuperare la pagina successiva.

Campi di risposta (per utente)

Campo	Descrizione
`user.id`	Identificatore univoco per l'utente.
`user.email_address`	L'indirizzo email dell'utente.
`chat_metrics.distinct_conversation_count`	Numero di conversazioni distinte, specificamente all'interno di Claude.ai.
`chat_metrics.message_count`	Numero totale di messaggi inviati, specificamente all'interno di Claude.ai.
`chat_metrics.distinct_projects_created_count`	Numero di progetti distinti creati, specificamente all'interno di Claude.ai.
`chat_metrics.distinct_projects_used_count`	Numero di progetti distinti utilizzati, specificamente all'interno di Claude.ai.
`chat_metrics.distinct_files_uploaded_count`	Numero di file distinti caricati, specificamente all'interno di Claude.ai.
`chat_metrics.distinct_artifacts_created_count`	Numero di artefatti distinti creati, specificamente all'interno di Claude.ai.
`chat_metrics.distinct_shared_artifacts_viewed_count`	Numero di artefatti condivisi distinti visualizzati, specificamente all'interno di Claude.ai.
`chat_metrics.thinking_message_count`	Numero di messaggi di riflessione (estesi), specificamente all'interno di Claude.ai.
`chat_metrics.distinct_skills_used_count`	Numero di competenze distinte utilizzate, specificamente all'interno di Claude.ai.
`chat_metrics.connectors_used_count`	Numero totale di connettori richiamati, specificamente all'interno di Claude.ai.
`chat_metrics.shared_conversations_viewed_count`	Numero di conversazioni condivise visualizzate, specificamente all'interno di Claude.ai.
`claude_code_metrics.core_metrics.commit_count`	Numero di commit git effettuati tramite Claude Code.
`claude_code_metrics.core_metrics.pull_request_count`	Numero di richieste pull create tramite Claude Code.
`claude_code_metrics.core_metrics.lines_of_code.added_count`	Righe di codice totali aggiunte.
`claude_code_metrics.core_metrics.lines_of_code.removed_count`	Righe di codice totali rimosse.
`claude_code_metrics.core_metrics.distinct_session_count`	Numero di sessioni Claude Code distinte.
`claude_code_metrics.tool_actions.edit_tool`	Conteggi accettati e rifiutati per lo strumento Edit.
`claude_code_metrics.tool_actions.multi_edit_tool`	Conteggi accettati e rifiutati per lo strumento Multi-Edit.
`claude_code_metrics.tool_actions.write_tool`	Conteggi accettati e rifiutati per lo strumento Write.
`claude_code_metrics.tool_actions.notebook_edit_tool`	Conteggi accettati e rifiutati per lo strumento Notebook Edit.
`web_search_count`	Totale delle invocazioni dello strumento di ricerca web. Questo si applica sia a claude.ai che all'utilizzo di claude code all'interno della tua organizzazione.

Metriche Office Agent (per utente)

Ogni record utente include anche un oggetto office_metrics con suddivisioni per prodotto per Excel e PowerPoint. Questo blocco è sempre presente in ogni record: le organizzazioni senza utilizzo di Office Agent vedono valori pari a zero anziché null.

L'oggetto office_metrics contiene due chiavi: excel e powerpoint.

Ogni chiave contiene gli stessi sei campi:

Campo	Descrizione
`office_metrics.[product].distinct_session_count*`	Numero di sessioni Office Agent distinte.
`office_metrics.[product].message_count`	Numero di messaggi inviati (uno per turno agente completato).
`office_metrics.[product].skills_used_count`	Invocazioni totali di competenze. Una singola competenza utilizzata cinque volte conta come cinque.
`office_metrics.[product].distinct_skills_used_count`	Numero di competenze distinte utilizzate.
`office_metrics.[product].connectors_used_count`	Invocazioni totali di connettori. Un singolo connettore utilizzato tre volte conta come tre.
`office_metrics.[product].distinct_connectors_used_count`	Numero di connettori distinti utilizzati.

*Nota: Dove [product] è uno di excel o powerpoint.

Metriche Claude Cowork (per utente)

Ogni record utente include anche un oggetto cowork_metrics con coinvolgimento Cowork per utente. Questo blocco è sempre presente in ogni record: le organizzazioni senza utilizzo di Cowork vedono valori pari a zero anziché null.

Campo	Descrizione
`cowork_metrics.distinct_session_count`	Numero di sessioni Cowork distinte.
`cowork_metrics.message_count`	Messaggi utente totali inviati in Cowork.
`cowork_metrics.action_count`	Chiamate di strumenti riuscite (Bash, Read, Edit, ecc.)
`cowork_metrics.dispatch_turn_count`	Turni agente completati nelle sessioni Dispatch (agente in background).
`cowork_metrics.skills_used_count`	Invocazioni totali di competenze. Una singola competenza utilizzata cinque volte conta come cinque.
`cowork_metrics.distinct_skills_used_count`	Numero di competenze distinte utilizzate.
`cowork_metrics.connectors_used_count`	Numero totale di invocazioni di connettori. Un singolo connettore utilizzato tre volte conta come tre.
`cowork_metrics.distinct_connectors_used_count`	Numero di connettori distinti utilizzati.

Richiesta di esempio

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/users?date=2025-01-01&limit=3"
   --header "x-api-key: $YOUR_API_KEY"

2. Riepilogo attività

GET /v1/organizations/analytics/summaries

Restituisce un riepilogo di alto livello dell'engagement e dell'utilizzo dei posti per giorno per la tua organizzazione in un intervallo di date specificato. La risposta è un elenco di giorni con conteggi aggregati all'interno dell'intervallo di date. Nota che la differenza massima tra ending_date e starting_date deve essere 31 giorni, e c'è un ritardo di tre giorni nella disponibilità dei dati. Questo è utile per tracciare gli utenti attivi giornalieri, le tendenze settimanali e mensili e l'allocazione dei posti a colpo d'occhio.

Definiamo "attivo" se una delle seguenti condizioni è vera:

L'utente ha inviato almeno un messaggio di chat su Claude (chat).
L'utente ha avuto almeno una sessione Claude Code (locale o remota) associata all'organizzazione C4E, con utilizzo di strumenti/attività git
L'utente ha avuto almeno una sessione Claude Cowork con utilizzo di strumenti o attività di messaggistica.

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`starting_date`	stringa	Sì	La data di inizio per il recupero dei dati, nel formato YYYY-MM-DD. C'è un ritardo di tre giorni nella disponibilità dei dati, quindi i dati più recenti a cui puoi accedere sono da tre giorni fa.
`ending_date`	stringa	No	La data di fine facoltativa per il recupero dei dati, nel formato YYYY-MM-DD. Questa è esclusiva.

Campi di risposta

Campo	Descrizione
`starting_date`	Primo giorno per il quale le metriche sono aggregate, interpretato come una data UTC. C'è un ritardo di tre giorni nella disponibilità dei dati, quindi i dati più recenti a cui puoi accedere sono da tre giorni fa.
`ending_date`	Ultimo giorno (esclusivo) per il quale le metriche sono aggregate, interpretato come una data UTC
`daily_active_user_count`	Numero di utenti attivi nella data specificata (in base al consumo di token).
`weekly_active_user_count`	Numero di utenti attivi entro la finestra mobile di 7 giorni che termina nella data specificata.
`monthly_active_user_count`	Numero di utenti attivi entro la finestra mobile di 30 giorni che termina nella data specificata.
`assigned_seat_count`	Numero totale di posti attualmente assegnati nella tua organizzazione.
`pending_invite_count`	Numero di inviti in sospeso che non sono ancora stati accettati.
`cowork_daily_active_user_count`	Numero di utenti con ≥1 sessione Cowork quel giorno
`cowork_weekly_active_user_count`	Numero di utenti con ≥1 sessione Cowork in un periodo mobile di 7 giorni.
`cowork_monthly_active_user_count`	Numero di utenti con ≥1 sessione Cowork in un periodo mobile di 30 giorni.

Nota: Le finestre mobili per i conteggi settimanali e mensili guardano indietro dalla data specificata (inclusa). Se i dati sono incompleti per alcuni giorni all'interno della finestra (ad esempio, se la data è meno di 30 giorni nel passato), il conteggio mensile potrebbe sottovalutare l'attività.

Richiesta di esempio

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/summaries?starting_date=2025-01-01"
   --header "x-api-key: $YOUR_API_KEY"

3. Utilizzo del progetto Chat

GET /v1/organizations/analytics/apps/chat/projects

Restituisce i dati di utilizzo suddivisi per progetto chat per una data specificata. I progetti sono specifici di Claude (chat), quindi questo endpoint si concentra su quella superficie. Ogni elemento mostra il nome del progetto, quanti utenti univoci hanno interagito con esso e il numero totale di conversazioni tenute in quel progetto.

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`date`	stringa	Sì	La data per cui recuperare le metriche, in formato YYYY-MM-DD. C'è un ritardo di tre giorni nella disponibilità dei dati, quindi i dati più recenti a cui puoi accedere sono da tre giorni fa.
`limit`	intero	No	Numero di record per pagina (predefinito: 100, massimo: 1000).
`page`	stringa	No	Token cursore dalla risposta precedente del campo `next_page` per recuperare la pagina successiva.

Campi di risposta (per progetto)

Campo	Descrizione
`project_name`	Il nome del progetto.
`project_id`	L'ID del progetto taggato, ad es. "claude_proj_{ID}"
`distinct_user_count`	Numero di utenti univoci che hanno utilizzato questo progetto nella data specificata.
`distinct_conversation_count`	Numero di conversazioni in questo progetto nella data specificata.
`message_count`	Numero totale di messaggi inviati all'interno di questo progetto nella data specificata.
`created_at`	Il timestamp di creazione del progetto.
`created_by`	`{id, email_address}` dell'utente che ha creato il progetto.

Richiesta di esempio

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/apps/chat/projects?date=2025-01-01&limit=50"
   --header "x-api-key: $YOUR_API_KEY"

4. Utilizzo delle competenze

GET /v1/organizations/analytics/skills

Restituisce i dati di utilizzo delle competenze sia in Claude (chat) che in Claude Code all'interno della tua organizzazione per una data specificata. Ogni elemento rappresenta una competenza e mostra quanti utenti univoci l'hanno utilizzata.

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`date`	stringa	Sì	La data per cui recuperare le metriche, in formato YYYY-MM-DD. C'è un ritardo di tre giorni nella disponibilità dei dati, quindi i dati più recenti a cui puoi accedere sono da tre giorni fa.
`limit`	integer	No	Numero di record per pagina (predefinito: 100, massimo: 1000).
`page`	string	No	Token cursore dalla risposta precedente's `next_page` campo per recuperare la pagina successiva.

Campi di risposta (per competenza)

Campo	Descrizione
`skill_name`	Il nome della competenza.
`distinct_user_count`	Numero di utenti univoci che hanno utilizzato questa competenza nella data specificata.
`chat_metrics.distinct_conversation_skill_used_count`	Numero di conversazioni distinte in cui la competenza è stata utilizzata almeno una volta, in chat.
`claude_code_metrics.distinct_session_skill_used_count`	Numero di sessioni remote distinte in cui la competenza è stata utilizzata almeno una volta, in Claude Code.

Metriche Office Agent (per competenza)

Ogni record di competenza include anche un oggetto office_metrics che riporta quante sessioni di Office Agent hanno utilizzato la competenza, suddivise per prodotto. Questo blocco è sempre presente: le organizzazioni senza utilizzo di Office Agent vedono tutti valori pari a zero.

Campo	Descrizione
`office_metrics.excel.distinct_session_skill_used_count`	Numero di sessioni distinte di Office Agent in Excel in cui questa competenza è stata utilizzata.
`office_metrics.powerpoint.distinct_session_skill_used_count`	Numero di sessioni distinte di Office Agent in PowerPoint in cui questa competenza è stata utilizzata.

Metriche Claude Cowork (per competenza)

Ogni record di competenza include anche un oggetto cowork_metrics che riporta quante sessioni di Cowork hanno utilizzato la competenza. Questo blocco è sempre presente: le organizzazioni senza utilizzo di Cowork vedono tutti valori pari a zero.

cowork_metrics.distinct_session_skill_used_count

Numero di sessioni distinte di Cowork in cui questa competenza è stata utilizzata almeno una volta.

Richiesta di esempio

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/skills?date=2025-01-01"
   --header "x-api-key: $YOUR_API_KEY"

5. Utilizzo dei connettori

GET /v1/organizations/analytics/connectors

Restituisce i dati di utilizzo di MCP/connettori sia in Claude (chat) che in Claude Code all'interno della tua organizzazione per una data specificata. Ogni elemento rappresenta un connettore e mostra quanti utenti univoci lo hanno utilizzato. I nomi dei connettori sono normalizzati da varie fonti: ad esempio, "Atlassian MCP server," "mcp-atlassian," e "atlassian_MCP" apparirebbero tutti come "atlassian."

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`date`	string	Yes	La data per cui recuperare le metriche, in formato YYYY-MM-DD. C'è un ritardo di tre giorni nella disponibilità dei dati, quindi i dati più recenti a cui puoi accedere sono da tre giorni fa.
`limit`	integer	No	Numero di record per pagina (predefinito: 100, massimo: 1000).
`page`	stringa	No	Token del cursore dal campo `next_page` di una risposta precedente per recuperare la pagina successiva.

Campi di risposta (per connettore)

Campo	Descrizione
`connector_name`	Il nome normalizzato del connettore.
`distinct_user_count`	Numero di utenti univoci che hanno utilizzato questo connettore nella data specificata.
`chat_metrics.distinct_conversation_connector_used_count`	Numero di conversazioni distinte in cui il connettore è stato utilizzato almeno una volta, in chat.
`claude_code_metrics.distinct_session_connector_used_count`	Numero di sessioni remote distinte in cui il connettore è stato utilizzato almeno una volta, in Claude Code.

Metriche di Office Agent (per connettore)

Ogni record del connettore include anche un oggetto office_metrics che riporta quante sessioni di Office Agent hanno utilizzato il connettore, suddivise per prodotto. Questo blocco è sempre presente: le organizzazioni senza utilizzo di Office Agent vedono tutti i valori a zero.

Campo	Descrizione
`office_metrics.excel.distinct_session_connector_used_count`	Numero di sessioni distinte di Office Agent in Excel in cui questo connettore è stato utilizzato.
`office_metrics.powerpoint.distinct_session_connector_used_count`	Numero di sessioni distinte di Office Agent in PowerPoint in cui questo connettore è stato utilizzato.

Metriche di Claude Cowork (per connettore)

Ogni record del connettore include anche un oggetto cowork_metrics che riporta quante sessioni di Cowork hanno utilizzato il connettore. Questo blocco è sempre presente: le organizzazioni senza utilizzo di Cowork vedono tutti i valori a zero.

Campo	Descrizione
`cowork_metrics.distinct_session_connector_used_count`	Numero di sessioni distinte di Cowork in cui questo connettore è stato utilizzato almeno una volta.

Richiesta di esempio

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/connectors?date=2025-01-01"
   --header "x-api-key: $YOUR_API_KEY"

Endpoint di costo e utilizzo

Nota: Gli endpoint di costo e utilizzo si applicano ai piani Enterprise basati sull'utilizzo. Per i piani Enterprise basati su posti, questi endpoint rifletteranno solo i crediti di utilizzo.

Gli endpoint di costo e utilizzo (disponibili ora in versione beta) forniscono alla tua organizzazione l'accesso programmatico ai dati di token e costo in USD per Claude (chat), Claude Code, Cowork, Office Agent e Claude in Chrome.

Ci sono quattro endpoint in due forme:

Forma	Endpoint	Restituisce
Per utente (una riga per utente, ordinata)	user_usage_report, user_cost_report	Utenti classificati per token o spesa in un intervallo di date.
Raggruppato (una riga per bucket di tempo, facoltativamente raggruppato)	usage_report, cost_report	Utilizzo o costo nel tempo, suddiviso per prodotto, modello o altre dimensioni.

Utilizza gli endpoint per utente per rispondere a "chi sono i miei maggiori spender?" Utilizza gli endpoint raggruppati per rispondere a "come sta andando l'utilizzo giorno dopo giorno, suddiviso per prodotto?"

Freschezza e finalità dei dati

I dati sono generalmente disponibili entro quattro ore dall'utilizzo sottostante, ma potrebbero richiedere fino a 24 ore. Ogni risposta include un timestamp data_refreshed_at che indica l'esportazione da cui è stata servita la risposta; l'utilizzo che si è verificato dopo quel watermark non è ancora riflesso.

I valori per una data specificata possono essere rivisti fino a 30 giorni mentre arrivano gli eventi tardivi e vengono eseguiti i riconciliamenti. Per i totali di qualità fatturazione, interroga date almeno 30 giorni nel passato.

Quando ending_at viene omesso (l'impostazione predefinita è "ora"), la risposta includerà una coda di dati dopo data_refreshed_at che è incompleta. Per risultati stabili tra le chiamate ripetute, imposta ending_at su un valore pari o precedente a un data_refreshed_at precedentemente restituito.

Limiti dell'intervallo di date

starting_at può essere fino a 365 giorni nel passato, e una singola query può coprire al massimo 31 giorni (ending_at - starting_at). Per coprire un periodo più lungo, emetti più query con finestre adiacenti. Nessun dato è disponibile prima del 2026-01-01.

Paginazione

Tutti e quattro gli endpoint di costo e utilizzo sono impaginati con un cursore opaco. La prima richiesta restituisce fino a limit righe più un cursore next_page; passa quel cursore invariato come parametro page nella richiesta successiva e ripeti finché has_more non è false.

Tratta next_page come opaco: passalo invariato nella richiesta successiva e invia gli stessi parametri di query su ogni pagina. Se una richiesta restituisce 400 o 410 con un messaggio sul cursore della pagina, scartalo e ricomincia dalla prima pagina.

Non modificare i parametri di query a metà sequenza. I cursori sono legati ai filtri e all'intervallo di date che li hanno emessi. Se modifichi products[], order_by, group_by[], l'intervallo di date o qualsiasi filtro e passi un cursore precedente, riceverai un errore 400.

Serializzazione dei parametri di elenco

I parametri di elenco utilizzano la notazione tra parentesi: ripeti il nome del parametro con [] per ogni valore.

products[]=chat&products[]=claude_code

L'oggetto Actor

Ogni riga di risultato per utente identifica l'utente che ha generato l'utilizzo.

{
  "type": "user_actor",
  "user_id": "user_01AbCdEfGh",
  "name": "Jane Smith",
  "email": "[email protected]"
}

Campo	Tipo	Descrizione
type	string	Sempre "user_actor".
user_id	string	L'ID dell'utente. Stesso valore accettato da user_ids[].
name	string o null	Il nome dell'utente. "Deleted User" se l'utente è stato eliminato.
email	string o null	L'indirizzo email dell'utente. Null quando l'utente è eliminato.
deleted	boolean	True se l'account è stato eliminato.

6. Utilizzo di token per utente

GET /v1/organizations/analytics/user_usage_report

Restituisce l'utilizzo di token per utente in un intervallo di date, ordinato in base alla metrica di token scelta.

Parametri di query

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
starting_at	Data e ora RFC 3339	Sì	—	Inizio dell'intervallo, inclusivo. Arrotondato all'inizio dell'ora in UTC. Deve essere entro gli ultimi 365 giorni.
ending_at	Data e ora RFC 3339	No	ora	Fine dell'intervallo, esclusiva. L'intervallo può durare al massimo 31 giorni.
products[]	uno o più tra chat, claude_code, cowork, office_agent, claude_in_chrome, claude_design	No	tutti i prodotti basati su seat	Solo superfici di prodotto basate su seat. Ripeti il parametro per più valori.
models[]	stringa, max 100 voci	No	all	Filtra per nomi di modello specifici (ad es. claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001).
user_ids[]	stringa, max 100 voci	No	all	Filtra per utenti specifici. Utile per cercare un insieme noto di utenti senza impaginare l'intera organizzazione.
context_windows[]	uno o più di 0-200k, 200k-1M	No	all	Filtra per livelli di prezzo specifici della finestra di contesto. Usa group_by[]=context_window per suddividere i valori per livello.
inference_geos[]	uno o più di global, us, not_available	No	all	Filtra per aree di inferenza specifiche. not_available corrisponde alle righe in cui l'area non è impostata. Usa group_by[]=inference_geo per suddividere i valori per area.
speeds[]	uno o più di fast, standard	No	all	Filtra per modalità di inferenza veloce o standard. Usa group_by[]=speed per suddividere i valori per modalità.
group_by[]	uno o più di product, model, context_window, inference_geo, speed	No	none	Suddividi la riga di ogni utente secondo le dimensioni specificate. Con dimensioni presenti, un utente può occupare più righe.
order_by	total_tokens, output_tokens, uncached_input_tokens	No	total_tokens	Metrica per ordinare.
exclude_deleted_users	booleano	No	false	Se true, le righe degli utenti eliminati vengono omesse.
order	desc, asc	No	desc	Direzione di ordinamento.
limit	intero 1–1000	No	20	Righe per pagina.
pagina	stringa cursore opaca	No	—	Il valore next_page da una risposta precedente.

Campi di risposta

Campo	Descrizione
organization_id	ID dell'organizzazione a cui appartiene la chiave API.
data	Array di voci, ordinate per order_by nella direzione specificata.
data[].actor	L'oggetto Actor per l'utente che ha generato l'utilizzo.
data[].product	Quando group_by[] include product, la superficie del prodotto. Altrimenti null.
data[].model	Quando group_by[] include model, il nome del modello. Altrimenti null.
data[].context_window	Quando group_by[] include context_window, il livello di contesto (0-200k o 200k-1M). Altrimenti null.
data[].inference_geo	Quando group_by[] include inference_geo, la regione di inferenza. Altrimenti null.
data[].speed	Quando group_by[] include speed: fast o standard. Altrimenti null.
data[].uncached_input_tokens	Token di input non serviti dalla cache del prompt.
data[].cache_creation.ephemeral_5m_input_tokens	Token scritti nella cache del prompt di 5 minuti.
data[].cache_creation.ephemeral_1h_input_tokens	Token scritti nella cache del prompt di 1 ora.
data[].cache_read_input_tokens	Token di input serviti dalla cache del prompt.
data[].output_tokens	Token di output generati.
data[].total_tokens	Somma di tutti i componenti di token sopra. L'order_by=total_tokens predefinito ordina su questo valore.
data[].server_tool_use.web_search_requests	Numero di chiamate dello strumento di ricerca web.
data[].requests	Numero di richieste API
has_more	Se esiste un'altra pagina.
next_page	Cursore opaco per la pagina successiva; null quando has_more è false.
data_refreshed_at	Timestamp dell'esportazione dati da cui è stata servita questa risposta.

Richiesta di esempio

curl "https://api.anthropic.com/v1/organizations/analytics/user_usage_report?starting_at=2026-03-01T00:00:00Z&products[]=claude_code&order_by=output_tokens&limit=20" \

--header "x-api-key: $YOUR_API_KEY"

7. Costo per utente

GET /v1/organizations/analytics/user_cost_report

Restituisce il costo in USD per utente in un intervallo di date, ordinato per importo scontato o prezzo di listino.

Parametri di query

Come user_usage_report, con queste differenze:

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
order_by	amount, list_amount	No	amount	Metrica per ordinare.
group_by[]	uno o più tra product, model, context_window, inference_geo, speed, cost_type, token_type	No	nessuno	Suddividi la riga di ogni utente secondo le dimensioni specificate. cost_type restituisce una riga per componente di costo (token, ricerca web, esecuzione codice); token_type restituisce una riga per tipo di token.

Tutti gli altri parametri (starting_at, ending_at, products[], models[], user_ids[], order, limit, page) sono identici.

Campi di risposta

Campo	Descrizione
organization_id	ID dell'organizzazione a cui appartiene la chiave API.
data	Array di voci, ordinate per order_by nella direzione specificata.
data[].actor	L'oggetto Actor per l'utente che ha generato il costo.
data[].product, data[].model, data[].context_window, data[].inference_geo, data[].speed	Se il valore group_by[] corrispondente è impostato, il valore della dimensione. Altrimenti null.
data[].currency	Sempre "USD".
data[].amount	Importo in centesimi frazionari — costo di consumo grezzo dopo sconti negoziati. Ad esempio, "41280.000000" è $412,80. Il valore è sommato su tutti i prodotti nel filtro products[].
data[].list_amount	Importo a prezzo di listino (pre-sconto) in centesimi frazionari, stesso formato.
data[].cost_type	Quando group_by[] include cost_type: uno tra tokens, web_search, code_execution. null se non impostato.
data[].token_type	Quando group_by[] include token_type: uno tra uncached_input_tokens, output_tokens, cache_read_input_tokens, cache_creation.ephemeral_5m_input_tokens, cache_creation.ephemeral_1h_input_tokens. Non-null solo su righe dove cost_type è tokens.
data[].requests	Numero di richieste API
has_more	Se esiste un'altra pagina.
next_page	Cursore opaco per la pagina successiva.
data_refreshed_at	Timestamp dell'esportazione dati da cui è stata servita questa risposta.

Analisi degli importi

amount e list_amount sono stringhe decimali denominate in centesimi. "41280.000000" rappresenta 41.280 centesimi (US $412,80). Per convertire in dollari, analizza come decimale e dividi per 100. Evita l'analisi in virgola mobile binaria per valori che potrebbero superare diversi milioni di dollari.

Richiesta di esempio

curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-03-01T00:00:00Z&order_by=amount&limit=20" \

--header "x-api-key: $YOUR_API_KEY"

8. Utilizzo dei token nel tempo

GET /v1/organizations/analytics/usage_report

Restituisce l'utilizzo dei token nel tempo, raggruppato per minuto, ora o giorno, facoltativamente suddiviso per prodotto, modello, finestra di contesto, regione di inferenza o velocità.

Parametri di query

Campo	Tipo	Obbligatorio	Predefinito	Descrizione
starting_at	Data e ora RFC 3339	Sì	—	Inizio dell'intervallo, incluso. Deve essere entro gli ultimi 365 giorni. Arrotondato al limite bucket_width più vicino in UTC.
ending_at	Data e ora RFC 3339	No	ora	Fine dell'intervallo, esclusa. L'intervallo può durare al massimo 31 giorni. Arrotondato al limite bucket_width più vicino in UTC.
bucket_width	1m, 1h, 1d	No	1d	Granularità del bucket temporale: minuto, ora o giorno.
group_by[]	uno o più tra product, model, context_window, inference_geo, speed	No	nessuno	Dimensioni da suddividere all'interno di ogni bucket. Omettere per un singolo aggregato per bucket.
products[]	uno o più tra chat, claude_code, cowork, office_agent, claude_in_chrome, claude_design	No	tutti	Filtra per superfici di prodotto specifiche.
models[]	stringa, massimo 100 voci	No	tutti	Filtra per nomi di modello specifici.
context_windows[]	uno o più tra 0-200k, 200k-1M	No	tutti	Filtra per livelli di prezzo della finestra di contesto specifici. Usa group_by[]=context_window per suddividere i valori per livello.
inference_geos[]	uno o più tra global, us, not_available	No	tutti	Filtra per regioni di inferenza specifiche. not_available corrisponde alle righe in cui la regione non è impostata. Usa group_by[]=inference_geo per suddividere i valori per regione.
speeds[]	uno o più tra veloce, standard	No	tutto	Filtra per modalità di inferenza veloce o standard.
user_ids[]	stringa, massimo 100 voci	No	tutto	Filtra per utenti specifici.
limite	intero	No	varia	Bucket per pagina. Predefinito e massimo variano per bucket_width: 1d → 7 (max 31); 1h → 24 (max 168); 1m → 60 (max 256).
pagina	stringa cursore opaca	No	—	Il valore next_page da una risposta precedente.

Campi di risposta

Campo	Descrizione
organization_id	ID dell'organizzazione a cui appartiene la chiave API.
dati	Array di voci, una per bucket temporale.
dati[].starting_at	Inizio bucket.
dati[].ending_at	Fine bucket.
dati[].risultati	Array di voci, una per gruppo all'interno del bucket. Una singola voce con tutti i campi dimensione null quando group_by[] è omesso.
dati[].risultati[].prodotto, .modello, .context_window, .inference_geo, .velocità	Quando il valore group_by[] corrispondente è impostato, il valore della dimensione. Altrimenti null.
dati[].risultati[].uncached_input_tokens	Token di input non serviti dalla cache del prompt.
dati[].risultati[].cache_creation.ephemeral_5m_input_tokens	Token scritti nella cache del prompt di 5 minuti.
dati[].risultati[].cache_creation.ephemeral_1h_input_tokens	Token scritti nella cache del prompt di 1 ora.
dati[].risultati[].cache_read_input_tokens	Token di input serviti dalla cache del prompt.
dati[].risultati[].output_tokens	Token di output generati.
dati[].risultati[].server_tool_use.web_search_requests	Numero di chiamate dello strumento di ricerca web.
ha_più	Se esistono più bucket.
pagina_successiva	Cursore opaco per la pagina successiva.
data_refreshed_at	Timestamp dell'esportazione dati da cui è stata servita questa risposta.

Richiesta di esempio

curl "https://api.anthropic.com/v1/organizations/analytics/usage_report?starting_at=2026-03-01T00:00:00Z&bucket_width=1d&group_by[]=product" \

--header "x-api-key: $YOUR_API_KEY"

9. Costo nel tempo

GET /v1/organizations/analytics/cost_report

Restituisce costo USD nel tempo, raggruppato e diviso nello stesso modo di usage_report.

Parametri di query

Uguali a usage_report (bucket_width, group_by[], filters, limit, page). I valori group_by[] accettano inoltre cost_type e token_type su questo endpoint.

Campi di risposta

Campo	Descrizione
organization_id	ID dell'organizzazione a cui appartiene la chiave API.
data	Array di voci, una per bucket temporale.
data[].starting_at	Inizio del bucket.
data[].ending_at	Fine del bucket.
data[].results	Array di voci, una per gruppo all'interno del bucket.
data[].results[].product, .model, .context_window, .inference_geo, .speed	Quando il valore group_by[] corrispondente è impostato, il valore della dimensione. Altrimenti null.
data[].results[].cost_type	Quando group_by[] include cost_type: tokens, web_search o code_execution. null quando non impostato.
data[].results[].token_type	Quando group_by[] include token_type: uno dei tipi di token elencati nell'endpoint 7. Solo endpoint Cost — token_type è rifiutato su usage_report.
data[].results[].currency	Sempre "USD".
data[].results[].amount	Importo in centesimi frazionari — costo di consumo grezzo dopo sconti negoziati.
data[].results[].list_amount	Importo a prezzo di listino (pre-sconto) in centesimi frazionari.
has_more	Se esistono più bucket.
next_page	Cursore opaco per la pagina successiva.
data_refreshed_at	Timestamp dell'esportazione dati da cui è stata servita questa risposta.

Richiesta di esempio

curl "https://api.anthropic.com/v1/organizations/analytics/cost_report?starting_at=2026-03-01T00:00:00Z&bucket_width=1d&group_by[]=model" \

--header "x-api-key: $YOUR_API_KEY"