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 per l'utilizzo di Claude e Claude Code all'interno della tua organizzazione Enterprise. Che tu stia creando dashboard interni per l'attività degli utenti o tracciando l'adozione di progetti, questa API fornisce le metriche aggregate 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 del 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. Siamo solitamente consapevoli di tali problemi, ma ti preghiamo di segnalarlo al tuo CSM se desideri una verifica o sospetti qualcos'altro.

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 lo scope 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, 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 lo scope read:analytics. Puoi creare e gestire le chiavi API dalle impostazioni admin di claude.ai nella sezione API Keys.

Esempio di intestazioni di richiesta:

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 prossima richiesta per recuperare la pagina successiva di risultati.

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. 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.

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 precedente a 1/1/26 (prima disponibilità) o una data che è oggi o nel futuro. La disponibilità dei dati è ritardata di tre giorni.
404	La chiave API è mancante, non valida o non ha lo scope `read:analytics`.
429	Limite di velocità superato. Troppe richieste.
503	Errore transitorio, si prega di riprovare.

Limitazione della velocità

Abbiamo dei limiti di velocità predefiniti. Se non è sufficiente per il tuo caso d'uso, ci piacerebbe capire il motivo. Se necessario, possiamo regolare i limiti di velocità per la tua organizzazione—contatta il tuo CSM.

Endpoint

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 loro attività su Claude (chat) e Claude Code.

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`date`	string	Sì	La data per cui recuperare le metriche, in formato YYYY-MM-DD.
`limit`	integer	No	Numero di record per pagina (predefinito: 20, massimo: 1000).
`page`	string	No	Token del 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 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 caricati, specificamente all'interno di Claude.ai.
`chat_metrics.distinct_artifacts_created_count`	Numero di artefatti creati, 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.
`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 pull request create tramite Claude Code.
`claude_code_metrics.core_metrics.lines_of_code.added_count`	Numero totale di righe di codice aggiunte.
`claude_code_metrics.core_metrics.lines_of_code.removed_count`	Numero totale di righe di codice rimosse.
`claude_code_metrics.core_metrics.distinct_session_count`	Numero di sessioni distinte di Claude Code.
`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 del codice Claude 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`	Totale delle invocazioni 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`	Totale delle invocazioni 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.

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 per un determinato intervallo di date. 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

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`starting_date`	stringa	Sì	La data di inizio per recuperare i 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 recuperare i dati, nel formato YYYY-MM-DD. Questo è esclusivo.

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 (basato sul 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.

Nota: Le finestre mobili per i conteggi settimanali e mensili guardano indietro dalla data specificata (inclusa). Se i dati sono incompleti per alcuni giorni entro la finestra (ad esempio, se la data è inferiore a 30 giorni fa), 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, 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.
`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 specifica. Ogni elemento rappresenta una competenza e mostra quanti utenti univoci l'hanno utilizzata.

Parametri di query

Campo	Tipo	Obbligatorio	Descrizione
`date`	string	Sì	La data per cui recuperare le metriche, 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.
`limit`	integer	No	Numero di record per pagina (predefinito: 100, massimo: 1000).
`page`	string	No	Token cursore dalla risposta precedente nel campo `next_page` 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 di 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.

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 specifica. Ogni elemento rappresenta un connettore e mostra quanti utenti univoci l'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	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 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 la skill è stata utilizzata almeno una volta, in Claude Code.

Metriche 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.

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"