> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ottenere le chiamate agli strumenti dell'agente Devin > Conta le chiamate agli strumenti effettuate dall'agente, come la ricerca sul web o l'esecuzione di comandi, dal tuo team in Devin Desktop e nella Devin CLI, raggruppate per strumento, utente, modello, IDE o sistema operativo. Questo è un **endpoint v2** che usa l'autenticazione tramite token Bearer e parametri di query, a differenza dell'API di analisi v1, che usa chiavi di servizio nel corpo della richiesta. Vedi [Autenticazione](#authentication) più avanti. Questo endpoint **non** è pensato per il monitoraggio dell'utilizzo in tempo reale. Il limite di frequenza è basso (10 richieste all'ora per team). Usalo per report periodici ed esportazioni di dati in blocco.

Autenticazione

Questo endpoint usa l'autenticazione tramite **token Bearer**. Includi il tuo token nell'intestazione `Authorization`: ``` Authorization: Bearer ``` Usa una API key dell'utente di servizio Devin con l'autorizzazione **Use Local Analytics API** oppure una chiave di servizio Windsurf con l'autorizzazione **Lettura analytics**. Per sapere come crearle, consulta [Autenticazione](/it/desktop/accounts/api-reference/analytics-v2-introduction#authentication). A differenza dell'origine dati v1 [`cascade_tool_usage`](/it/desktop/accounts/api-reference/cascade-analytics#cascade_tool_usage), questo endpoint accetta le API key dell'utente di servizio Devin, quindi i team sulla piattaforma Cognition possono monitorare l'utilizzo degli strumenti senza una chiave di servizio Windsurf.

Metriche

Il parametro di query `metric` è obbligatorio e al momento accetta solo `calls`, ovvero il numero di chiamate agli strumenti effettuate dall'agente. Compare come campo intero `calls` in ogni riga. Le richieste senza `metric`, o che specificano un'altra metrica, falliscono con errore `400`. Le chiamate agli strumenti vengono conteggiate quando l'agente invoca uno strumento in [Devin Desktop](/it/desktop/introducing-devin-desktop) o nella [Devin CLI](/it/cli) (inclusa la CLI eseguita come agente all'interno di altri editor), con qualsiasi modello. Anche il parametro `product` è obbligatorio e al momento accetta solo `agent`.

Strumenti

Raggruppa per `tool` per suddividere le chiamate in base alla categoria di strumento. Ogni riga include quindi un campo `tool` con uno dei seguenti valori: | Strumento | Descrizione | | - | - | | `SEARCH_WEB` | Ricerca sul web, recupero di pagine web e uso del browser | | `RUN_COMMAND` | Comandi della shell e interazione con i processi in esecuzione | | `VIEW_FILE` | Lettura di file e notebook | | `CODE_ACTION` | Modifica, scrittura e applicazione di patch ai file | | `GREP_SEARCH` | Ricerca nel contenuto dei file e nel codice | | `FIND` | Ricerca di file per nome | | `LIST_DIRECTORY` | Elenco del contenuto delle directory | | `MCP_TOOL` | Chiamata di strumenti dei server MCP ed elenco di server MCP, strumenti o risorse | | `SKILL` | Elenco, ricerca e invocazione di skill | | `ASK_USER_QUESTION` | Domande all'utente | | `MEMORY` | Lettura e scrittura di memorie | | `PROPOSE_CODE` | Proposta di modifiche al codice | | `PROXY_WEB_SERVER` | Anteprima nel browser di un server web locale | | `DEPLOY_WEB_APP` | Distribuzione di un'applicazione web | | `MQUERY` | Ricerca nella codebase (Riptide) | | `DEEPWIKI` | Richieste DeepWiki | | `CODEMAP_GENERATION`, `CODEMAP_SUGGESTIONS` | Richieste Codemaps | | `OTHER` | Strumenti della Devin CLI che non rientrano nelle categorie precedenti | Non tutte le categorie valgono per ogni client: `LIST_DIRECTORY`, `MEMORY`, `PROPOSE_CODE`, `PROXY_WEB_SERVER`, `DEPLOY_WEB_APP` e `MQUERY` vengono registrate per l'agente di Devin Desktop, mentre i nuovi strumenti della Devin CLI a cui non è ancora stata assegnata una categoria vengono conteggiati in `OTHER`.

Raggruppamento e granularità

Usa `granularity` e `group_by` per controllare la struttura dei dati restituiti: * **Nessuna granularità o raggruppamento** — restituisce una singola riga aggregata per l'intero intervallo di date * **`granularity=daily`** — ogni riga include un `timestamp` in formato `YYYY-MM-DD` * **`granularity=monthly`** — ogni riga include un `timestamp` in formato `YYYY-MM` * **`group_by=tool`** — ogni riga include un `tool` (vedi [Strumenti](#tools) sopra) * **`group_by=user`** — ogni riga include un `user_id`, oltre a un `user_email` se ne è registrato uno per quell'utente * **`group_by=model_uid`** — ogni riga include un `model_uid` * **`group_by=ide`** — ogni riga include un `ide` * **`group_by=ide,ide_version`** — ogni riga include `ide` e `ide_version` (per raggruppare per `ide_version` è necessario includere anche `ide`) * **`group_by=os`** — ogni riga include un `os`, ad esempio `darwin` (macOS), `windows` o `linux` Le dimensioni possono essere combinate: ad esempio, `group_by=user,tool` indica quante volte ciascun utente ha invocato ciascuno strumento. Le dimensioni `session` e `source` di [Get Output](/it/desktop/accounts/api-reference/get-output) non sono supportate in questo caso. Si applicano gli stessi filtri `models`, `group_id` e `user_id` di [Get Consumption](/it/desktop/accounts/api-reference/get-consumption), oltre a un filtro `tool` che limita il conteggio a una sola categoria di strumenti (ad esempio `tool=SEARCH_WEB`). `tool` è accettato solo da questo endpoint: se lo passi a un altro endpoint di Analytics API v2, la richiesta non riesce e restituisce `400`.

Esempio

Conta le ricerche sul web per utente nell'arco di una settimana: ```bash theme={null} curl "https://server.codeium.com/api/v2alpha/analytics/tools?metric=calls&product=agent&start_date=2026-10-13&end_date=2026-10-19&group_by=user&tool=SEARCH_WEB" \ -H "Authorization: Bearer $DEVIN_API_KEY" ``` Ogni riga riporta il conteggio di `SEARCH_WEB` di un utente. Per visualizzare invece tutte le categorie per ciascun utente, rimuovi il filtro `tool` e aggiungi `group_by=user,tool`.

Paginazione

I risultati sono paginati con una dimensione di pagina predefinita di 1.000 righe (massimo 10.000). Se sono disponibili altri risultati, la risposta include un `next_page_cursor` nell'oggetto `pagination`. Passalo come parametro di query `page_cursor` in una richiesta che ripeta per il resto i parametri di query originali. I cursori sono vincolati all'endpoint che li ha emessi: un cursore proveniente da `/consumption` o `/output` viene rifiutato con `400`. I cursori di pagina scadono dopo 24 ore. La richiesta di una pagina successiva non viene conteggiata come nuova query ai fini del tuo limite di frequenza.

Limiti di frequenza

Questo endpoint ha un limite di **10 richieste all'ora** per team. Se superi questo limite, il server restituisce `429 Too Many Requests` con un'intestazione `Retry-After`. La paginazione di una query precedente (tramite un `next_page_cursor`) **non** viene conteggiata ai fini di questo limite: conta solo la query iniziale di ciascun report. Il limite è basso perché questo endpoint è pensato per la reportistica periodica, non per il monitoraggio dell'utilizzo in tempo reale. ## OpenAPI ````yaml it/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/tools openapi: 3.1.0 info: title: Devin Desktop Analytics API v2 version: 2.0.0 description: > L'API di analisi v2 fornisce analisi del consumo di crediti e ACU, degli utenti attivi, dell'output dell'agente (righe di codice accettate) e analytics delle chiamate agli strumenti dell'agente per i team Enterprise. I dati provengono da aggregati su base oraria e supportano filtri flessibili, raggruppamento e paginazione basata su cursore. servers: - url: https://server.codeium.com security: - bearerAuth: [] paths: /api/v2alpha/analytics/tools: get: summary: Recupera le analytics delle chiamate agli strumenti dell'agente description: > Conta le chiamate agli strumenti effettuate dall'agente per il team autenticato. Il parametro obbligatorio `metric` accetta solo `calls`, il numero di chiamate agli strumenti effettuate dall'agente in Devin Desktop e Devin CLI, restituito come campo intero in ogni riga. I risultati possono essere filtrati per intervallo di date, prodotto, modello, gruppo e utente, e raggruppati secondo le stesse dimensioni della consumption (eccetto `session`), con l'aggiunta di `tool`, la categoria dello strumento, ad esempio `SEARCH_WEB` o `RUN_COMMAND`. Questi endpoint sono progettati per la reportistica periodica e l'esportazione in blocco. **Non** sono destinati al monitoraggio dell'utilizzo in tempo reale: il limite di richieste è basso (10 richieste all'ora per team). operationId: getTools parameters: - name: metric in: query required: true schema: type: string description: > Metrica da restituire; compare come campo in ogni riga. Metriche supportate: - `calls` — numero di chiamate agli strumenti effettuate dall'agente example: calls - name: start_date in: query required: true schema: type: string format: date description: Data di inizio dell'intervallo (inclusa) nel formato `YYYY-MM-DD`. example: '2026-10-01T00:00:00.000Z' - name: end_date in: query required: true schema: type: string format: date description: >- Data di fine dell'intervallo (inclusa) nel formato `YYYY-MM-DD`. L'intervallo non deve superare 90 giorni. example: '2026-10-31T00:00:00.000Z' - name: product in: query required: true schema: type: string enum: - agent description: Prodotto per cui recuperare le chiamate agli strumenti. example: agent - name: granularity in: query required: false schema: type: string enum: - daily - monthly description: > Granularità temporale per il raggruppamento dei risultati. Quando è specificata, ogni riga include un campo `timestamp`. Se omessa, i risultati vengono aggregati sull'intero intervallo di date. - name: group_by in: query required: false schema: type: string description: > Elenco delle dimensioni, separate da virgole, in base alle quali raggruppare i risultati. Dimensioni supportate: - `tool` — include `tool` in ogni riga (la categoria dello strumento, come `SEARCH_WEB` o `RUN_COMMAND`) - `user` — include `user_id` in ogni riga, oltre a `user_email` se registrato per l'utente - `model_uid` — include `model_uid` in ogni riga - `ide` — include `ide` in ogni riga - `ide_version` — include `ide_version` in ogni riga; richiede che sia incluso anche `ide` - `os` — include `os` in ogni riga example: user,tool - name: models in: query required: false schema: type: string description: >- Elenco degli UID dei modelli, separati da virgole, in base ai quali filtrare i risultati. example: swe-2-high,claude-4-sonnet - name: tool in: query required: false schema: type: string description: > Limita il conteggio a una sola categoria di strumenti, come `SEARCH_WEB` o `RUN_COMMAND` (corrispondenza esatta). Accettato solo da questo endpoint. example: SEARCH_WEB - name: group_id in: query required: false schema: type: string description: >- Filtra i risultati per includere solo gli utenti di un gruppo specifico. La chiave di servizio deve avere accesso a questo gruppo. Non supportato con le API key degli utenti di servizio Devin. - name: user_id in: query required: false schema: type: string description: >- Filtra i risultati per includere solo un utente specifico (UID auth). - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 10000 default: 1000 description: Numero massimo di righe da restituire per pagina. - name: page_cursor in: query required: false schema: type: string description: >- Cursore opaco ricavato da `pagination.next_page_cursor` di una risposta precedente, per recuperare la pagina successiva. Passa lo stesso valore di `metric` usato nella richiesta che ha generato il cursore; i cursori generati da altri endpoint vengono rifiutati. responses: '200': description: Dati delle chiamate agli strumenti restituiti correttamente. content: application/json: schema: $ref: '#/components/schemas/ToolsResponse' examples: by_user_tool: summary: Ricerche sul web e comandi per utente value: data: - user_id: user_abc123 user_email: alice@example.com tool: RUN_COMMAND calls: 1842 - user_id: user_abc123 user_email: alice@example.com tool: SEARCH_WEB calls: 57 pagination: next_page_cursor: null metadata: data_freshness: '2026-10-20T02:00:00.000Z' query_time_ms: 1104 team_id: team_abc123 daily_total: summary: granularity=daily senza raggruppamento value: data: - timestamp: '2026-10-13T00:00:00.000Z' calls: 48210 - timestamp: '2026-10-14T00:00:00.000Z' calls: 51377 pagination: next_page_cursor: null metadata: data_freshness: '2026-10-20T02:00:00.000Z' query_time_ms: 870 team_id: team_abc123 '400': description: Parametri della richiesta non validi. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_metric: value: error: metric is required bad_metric: value: error: 'unsupported metric: loc_inserted (supported: calls)' missing_product: value: error: product is required bad_group_by: value: error: 'unsupported group_by dimension for tools: session' '401': description: Autenticazione non riuscita o autorizzazioni insufficienti. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_auth: value: error: missing Authorization header invalid_key: value: error: invalid service key insufficient_permissions: value: error: insufficient permissions '403': description: >- Il cursore di pagina fornito non appartiene al team autenticato o al gruppo richiesto. content: application/json: schema: $ref: '#/components/schemas/Error' examples: cursor_team_mismatch: value: error: page cursor does not belong to this team '405': description: Metodo HTTP non consentito (è supportato solo `GET`). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Limite di richieste superato (10 richieste all'ora per team). La paginazione dei risultati di una richiesta precedente non viene conteggiata ai fini di questo limite. headers: Retry-After: schema: type: string description: Tempo di attesa consigliato prima di riprovare. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: rate limit exceeded '503': description: >- Il servizio di analisi non è disponibile (ad es. nelle distribuzioni autogestite). content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: ToolsResponse: type: object required: - data - pagination - metadata properties: data: type: array items: $ref: '#/components/schemas/ToolsRow' description: Array di righe di dati sulle chiamate agli strumenti. pagination: type: object properties: next_page_cursor: type: - string - 'null' description: > Cursore opaco per recuperare la pagina successiva dei risultati. Passa questo valore come parametro di query `page_cursor` in una richiesta successiva. `null` quando non ci sono altre pagine. I cursori di pagina scadono dopo 24 ore. metadata: type: object properties: data_freshness: type: string format: date-time description: >- Timestamp che indica quando sono stati aggiornati l'ultima volta i dati sottostanti (troncato all'ora). query_time_ms: type: integer format: int64 description: Tempo di esecuzione della query server-side in millisecondi. team_id: type: string description: >- L'ID del team determinato a partire dalla chiave di servizio autenticata. group_id: type: string description: >- L'ID del gruppo a cui sono limitati i risultati. Presente solo quando è stato fornito `group_id`. Error: type: object required: - error properties: error: type: string description: Messaggio di errore comprensibile all'utente. ToolsRow: type: object required: - calls properties: timestamp: type: string description: > Intervallo temporale della riga. Il formato dipende da `granularity`: `YYYY-MM-DD` per la granularità giornaliera, `YYYY-MM` per quella mensile. Presente solo quando è specificato `granularity`. examples: - '2026-10-15T00:00:00.000Z' - 2026-10 user_id: type: string description: >- Identificatore dell'utente (UID auth). Presente solo quando `group_by` include `user`. user_email: type: string description: >- Indirizzo email dell'utente. Presente solo quando `group_by` include `user` e per l'utente è registrato un indirizzo email. examples: - alice@example.com model_uid: type: string description: >- Identificatore del modello. Presente solo quando `group_by` include `model_uid`. examples: - swe-2-high ide: type: string description: Nome dell'IDE. Presente solo quando `group_by` include `ide`. examples: - windsurf - devin-cli ide_version: type: string description: >- Versione dell'IDE. Presente solo quando `group_by` include `ide_version` (che richiede anche `ide`). examples: - 3000.10.48 os: type: string description: >- Sistema operativo da cui proviene la richiesta. Presente solo quando `group_by` include `os`. examples: - darwin - windows - linux tool: type: string description: > Categoria dello strumento utilizzato per le chiamate, ad esempio `SEARCH_WEB`, `RUN_COMMAND`, `VIEW_FILE`, `CODE_ACTION`, `GREP_SEARCH`, `FIND`, `MCP_TOOL`, `SKILL` o `ASK_USER_QUESTION`. Gli strumenti di Devin CLI senza categoria sono indicati come `OTHER`. Presente solo quando `group_by` include `tool`. examples: - SEARCH_WEB - RUN_COMMAND calls: type: integer format: int64 description: >- Numero di chiamate agli strumenti effettuate dall'agente in questa riga. securitySchemes: bearerAuth: type: http scheme: bearer description: > Una chiave di servizio con autorizzazione **Analisi Read**, passata come token Bearer nell'header `Authorization`. Crea una chiave di servizio nelle [impostazioni del team](https://windsurf.com/team/settings), nella sezione "Service Keys". ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.