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

# API di Analytics (Enterprise SaaS)

> Recupera tramite API i dati di analytics di Devin Desktop, incluse le metriche di completamento automatico, chat, comando, Cascade e PCW. Supporta filtri, aggregazioni e raggruppamenti personalizzati.

<div id="overview">
  ## Panoramica
</div>

Devin Desktop supporta un'API per l'analytics personalizzata. Consente di recuperare dati da completamento automatico, chat e comandi, con una varietà di filtri, raggruppamenti e aggregazioni.

Forniamo tutti gli esempi in curl; possono poi essere convertiti in richieste HTTP in altri linguaggi.

<Note>L'API di Analytics è disponibile per i piani Enterprise</Note>

<div id="user-data-analytics-api-specification">
  ## Specifica dell'API di analisi dei dati utente
</div>

I dati della tabella Users nella pagina Teams possono essere ottenuti con il seguente comando:

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "<SERVICE_KEY>",
  "group_name": "<GROUP_NAME>",
  "start_timestamp": "<START_TIMESTAMP>",
  "end_timestamp": "<END_TIMESTAMP>"
}' \
https://server.codeium.com/api/v1/UserPageAnalytics
```

**SERVICE\_KEY**: La chiave di servizio: un utente amministratore può crearne una dalla sezione relativa alla chiave di servizio nella pagina Settings. Il ruolo della chiave di servizio deve disporre delle autorizzazioni "Teams sola lettura".

**GROUP\_NAME**: Il nome di un gruppo su cui filtrare. Questo campo è facoltativo.

**START\_TIMESTAMP/END\_TIMESTAMP**: Timestamp nel formato RFC 3339, quindi ad es. 2023-01-01T00:00:00Z

<div id="example-output">
  #### **Esempio di output**
</div>

```json theme={null}
{
  "userTableStats": [
    {
      "name": "Alice",
      "email": "alice@cognition.ai",
      "lastUpdateTime": "2024-10-10T22:56:10.771591Z",
      "apiKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "activeDays": 178,
      "teamStatus": "USER_TEAM_STATUS_APPROVED"
    },
    {
      "name": "Bob",
      "email": "bob@cognition.ai",
      "lastUpdateTime": "2024-10-10T18:11:23.980237Z",
      "apiKey": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "activeDays": 462,
      "teamStatus": "USER_TEAM_STATUS_APPROVED"
    },
    {
      "name": "Charlie",
      "email": "charlie@cognition.ai",
      "lastUpdateTime": "2024-10-10T16:43:46.117870Z",
      "apiKey": "cccccccc-cccc-cccc-cccc-cccccccccccc",
      "activeDays": 237,
      "teamStatus": "USER_TEAM_STATUS_PENDING"
    }
  ]
}
```

<div id="cascade-analytics-api-specification">
  ## Specifica dell'API di Cascade Analytics
</div>

I dati specifici di Cascade visibili nella [pagina analytics](https://windsurf.com/team/analytics) possono essere recuperati tramite API.

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "<SERVICE_KEY>",
  "group_name": "<GROUP_NAME>",
  "start_timestamp": "<START_TIMESTAMP>",
  "end_timestamp": "<END_TIMESTAMP>",
  "emails": ["<EMAIL>","<EMAIL>,..."],
  "ide_types": ["<IDE_TYPE>","<IDE_TYPE>,..."],
  "query_requests": [
   {
    "<CASCADE_DATA_SOURCE>": {}
   }
  ]
}' \
https://server.codeium.com/api/v1/CascadeAnalytics
```

**SERVICE\_KEY**: La chiave di servizio - un utente amministratore può crearne una nuova da [Settings del team](https://windsurf.com/team/settings)

**GROUP\_NAME**: Il nome di un gruppo in base a cui filtrare. Questo campo è facoltativo. Non può essere impostato se è impostato il campo emails.

**START\_TIMESTAMP/END\_TIMESTAMP**: Timestamp in formato RFC 3339, quindi ad es. 2023-01-01T00:00:00Z

**EMAILS**: Un elenco di indirizzi email in base a cui filtrare. Questo campo è facoltativo. Non può essere impostato se è impostato il campo group\_name.

**IDE\_TYPES**: Un elenco di tipi di IDE in base a cui filtrare. Questo campo è facoltativo. I valori possibili sono descritti di seguito.

**QUERY\_REQUESTS**: Un elenco di richieste di interrogazione da effettuare. Questo campo è obbligatorio. I valori possibili di CASCADE\_DATA\_SOURCE sono descritti di seguito.

<div id="example-query">
  #### Esempio di query
</div>

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "my_random_test_key",
  "group_name": "my_group_name",
  "start_timestamp": "2025-01-01T00:00:00Z",
  "end_timestamp": "2025-01-02T00:00:00Z",
  "emails": ["my_email@cognition.ai", "my_email2@cognition.ai"],
  "ide_types": ["editor"],
  "query_requests": [
   {
    "cascade_lines": {}
   },
   {
    "cascade_runs": {}
   }
  ]
}' \
https://server.codeium.com/api/v1/CascadeAnalytics
```

<div id="ide-types">
  ### Tipi di IDE
</div>

Suddividiamo i dati di cascade in categorie in base al tipo di IDE. Se il campo ide\_types non è incluso nella query, vengono restituiti i dati per tutti i tipi di IDE. Se desideri recuperare i dati di un solo IDE, puoi usare una delle seguenti opzioni:

* "editor" per Devin Desktop Editor
* "jetbrains" per il plugin JetBrains
* "cli" per Devin CLI

<Note>Quando filtri per Devin CLI (`"cli"`), solo `cascade_runs` restituisce dati. Le origini dati `cascade_lines` e `cascade_tool_usage` non sono supportate per Devin CLI e restituiranno risultati vuoti.</Note>

<div id="cascade-data-sources">
  ### Origini dei dati di Cascade
</div>

Esistono tre possibili valori per CASCADE\_DATA\_SOURCE

<div id="source-cascade_lines">
  #### Fonte: cascade\_lines
</div>

Usa cascade\_lines per recuperare i dati relativi alle linee cascade suggerite e accettate ogni giorno.

Output di esempio:

```json theme={null}
{
  "queryResults": [
    {
      "cascadeLines": {
        "cascadeLines": [
          {
            "day": "2025-05-01T00:00:00Z",
            "linesSuggested": "206",
            "linesAccepted": "157"
          },
          {
            "day": "2025-05-02T00:00:00Z",
            "linesSuggested": "16"
          },
          {
            "day": "2025-05-03T00:00:00Z",
            "linesSuggested": "169",
            "linesAccepted": "168"
          }
        ]
      }
    }
  ]
}
```

**linesSuggested**: Il numero di righe suggerite nel giorno indicato.
**linesAccepted**: Il numero di righe accettate nel giorno indicato.

<div id="source-cascade_runs">
  #### Fonte: cascade\_runs
</div>

Usa cascade\_runs per recuperare i dati sull'utilizzo del modello, sul consumo di crediti e sulla modalità.

Output di esempio:

```json theme={null}
{
  "queryResults": [
    {
      "cascadeRuns": {
        "cascadeRuns": [
          {
            "day": "2025-05-01T00:00:00Z",
            "model": "Claude 3.7 Sonnet (Thinking)",
            "mode": "CONVERSATIONAL_PLANNER_MODE_DEFAULT",
            "messagesSent": "1",
            "cascadeId": "0d35c1f7-0a85-41d0-ac96-a04cd2d64444"
          },
          {
            "day": "2025-05-01T00:00:00Z",
            "model": "SWE-1",
            "mode": "UNKNOWN",
            "promptsUsed": "125",
            "cascadeId": "0d35c1f7-0a85-41d0-ac96-a04cd2d64444"
          },
          {
            "day": "2025-05-01T00:00:00Z",
            "model": "GPT-4.1 (promo)",
            "mode": "CONVERSATIONAL_PLANNER_MODE_DEFAULT",
            "messagesSent": "5",
            "cascadeId": "1f450ba3-06aa-4ba5-9e12-d3b98c2d33d3"
          },
        ]
      }
    }
  ]
}
```

**day**: La data del run.

**model**: Il modello utilizzato per il messaggio.

**mode**: La modalità del run. Una tra CONVERSATIONAL\_PLANNER\_MODE\_DEFAULT (per la modalità di scrittura), CONVERSATIONAL\_PLANNER\_MODE\_READ\_ONLY (per la modalità di sola lettura), CONVERSATIONAL\_PLANNER\_MODE\_NO\_TOOL (per la modalità legacy) oppure UNKNOWN.

**messagesSent**: Il numero di messaggi inviati.

**cascadeId**: L'ID del run. Questo ID può essere usato per capire quante conversazioni distinte sono state avviate (anziché quante volte l'utente invia un messaggio).

**promptsUsed**: Il numero di crediti utilizzati. Questo valore viene restituito in centesimi. Ad esempio, 0.25 crediti viene restituito come 25 e 1 credito come 100.

I dati restituiti dall'API sono in formato grezzo, il che può spiegare eventuali valori "UNKNOWN". Se utilizzi questa origine dati per le tue metriche, è consigliabile aggregare in base alle metriche specifiche che ti interessano (ad esempio, sommando il campo promptsUsed per comprendere i modelli di utilizzo degli utenti, messagesSent per comprendere il coinvolgimento degli utenti, ecc.), poiché è possibile che i dati relativi a modalità e prompt siano distribuiti tra più voci.

<div id="source-cascade_tool_usage">
  #### Fonte: cascade\_tool\_usage
</div>

Usa cascade\_tool\_usage per recuperare dati sull'utilizzo degli strumenti. Tieni presente che restituisce un conteggio aggregato degli utilizzi degli strumenti nel periodo specificato.

Esempio di output:

```json theme={null}
{
  "queryResults": [
    {
      "cascadeToolUsage": {
        "cascadeToolUsage": [
          {
            "tool": "CODE_ACTION",
            "count": "15"
          },
          {
            "tool": "LIST_DIRECTORY",
            "count": "20"
          },
          {
            "tool": "MCP_TOOL",
            "count": "12"
          },
          {
            "tool": "MEMORY",
            "count": "4"
          }
        ]
      }
    }
  ]
}
```

**tool**: Lo strumento usato per il messaggio.

**count**: Il numero di volte in cui lo strumento è stato usato.

Ecco una mappa degli enum restituiti e del nome leggibile associato, così come viene visualizzato nella UI:

* CODE\_ACTION: 'Modifica codice'
* VIEW\_FILE: 'Visualizza file'
* RUN\_COMMAND: 'Esegui comando'
* FIND: 'Strumento di ricerca'
* GREP\_SEARCH: 'Ricerca Grep'
* VIEW\_FILE\_OUTLINE: 'Struttura del file'
* MQUERY: 'Riptide'
* LIST\_DIRECTORY: 'Elenca directory'
* MCP\_TOOL: 'Tool MCP'
* PROPOSE\_CODE: 'Proponi codice'
* SEARCH\_WEB: 'Cerca sul Web'
* MEMORY: 'Memoria'
* PROXY\_WEB\_SERVER: 'Anteprima nel Browser'
* DEPLOY\_WEB\_APP: 'Distribuisci app web'

<div id="custom-analytics-api-specification">
  ## Specifica della Custom Analytics API
</div>

Alcune origini dati consentono query personalizzabili tramite la Custom Analytics API.

**Gli schemi completi per selezioni, filtri, aggregazioni e ordinamenti sono riportati nella sezione seguente, in formato JSON. Alla fine del documento troverai esempi di query per ciascuna delle tre origini dati, insieme a suggerimenti per il debug delle query.**

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "<SERVICE_KEY>",
  "group_name": "<GROUP_NAME>",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_<DATA_SOURCE>",
      "selections": [
        <LIST OF SELECTIONS>
      ],
      "filters": [
        <LIST OF FILTERS>
      ],
      "aggregations": [
        <LIST OF AGGREGATIONS>
      ],
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

**DATA\_SOURCE**: seleziona USER\_DATA, CHAT\_DATA, COMMAND\_DATA, PCW\_DATA oppure CASCADE\_DATA, a seconda che tu stia cercando dati di completamento automatico, chat, Command, PCW o Cascade.

**SERVICE\_KEY**: La chiave di servizio: un utente admin può crearne una nuova da [Settings del team](https://windsurf.com/team/settings). Il ruolo della chiave di servizio deve disporre dell'autorizzazione "Analytics Read".

**GROUP\_NAME**: Il nome di un gruppo in base a cui filtrare. Questo campo è facoltativo.

<div id="schemas">
  ## Schemi
</div>

<div id="selections">
  ### Selezioni
</div>

Le selezioni sono **obbligatorie**. Ogni selezione corrisponde a un valore su cui eseguire la query.

```json theme={null}
{
  "field": "<FIELD_NAME>",
  "name": "<NAME>",
  "aggregation_function": "QUERY_AGGREGATION_<AGGREGATION_FUNCTION>"
}
```

**FIELD\_NAME**: il campo che desideri recuperare. Vedi la sezione Campi disponibili di seguito.

**NAME**: un alias per il campo. Se non specificato, sarà la versione in minuscolo di \<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME>, ad es. sum\_num\_acceptances. Deve essere distinto da tutti gli altri nomi di campi e aggregazioni.

**AGGREGATION\_FUNCTION**: deve essere uno dei seguenti: UNSPECIFIED, COUNT, SUM, AVG, MAX, MIN. Se "aggregation\_function" non è specificato, il valore predefinito è UNSPECIFIED.

<div id="filters">
  ### Filtri
</div>

I filtri servono a restringere i dati in modo da includere solo gli elementi che soddisfano determinati criteri. Sono facoltativi.

```json theme={null}
{
  "name": "<NAME>",
  "value": "<VALUE>",
  "filter": "QUERY_FILTER_<FILTER>"
}
```

**NAME**: il nome del campo che desideri filtrare. Se l'elemento filtrato coincide con una Selection/Aggregation, deve essere uguale al nome del campo/dell'aggregazione.

**VALUE**: il valore da confrontare.

**FILTER**: uno tra EQUAL, NOT\_EQUAL, GREATER\_THAN, LESS\_THAN, GE (maggiore o uguale), LE (minore o uguale).

<div id="aggregations">
  ### Aggregazioni
</div>

Le aggregazioni vengono utilizzate per suddividere i dati in gruppi in base a un criterio specifico. Sono facoltative.

```json theme={null}
{
  "field": <FIELD_NAME>,
  "name": <NAME>
}
```

FIELD\_NAME: Il campo che desideri recuperare. Consulta la sezione Campi disponibili.

NAME: Un alias del campo. Deve essere distinto da tutti gli altri nomi di campi e aggregazioni.

<div id="available-fields">
  ## Campi disponibili
</div>

<div id="user-data">
  ### Dati utente
</div>

Tutti i dati della sorgente USER\_DATA sono aggregati per utente e per ora.

Nota: PCW (percentuale di codice scritto) ora ha una tabella dedicata e non dipende dalla tabella user\_data.

| **Nome campo**             | **Descrizione**                                                                                                                                                  | **Aggregazioni valide** |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| api\_key                   | Un hash della API key dell'utente.                                                                                                                               | UNSPECIFIED, COUNT      |
| date                       | La data UTC del completamento automatico o dei completamenti automatici.                                                                                         | UNSPECIFIED, COUNT      |
| date UTC-x                 | La data del completamento automatico, con uno scostamento di fuso orario. Per esempio, PST sarebbe "date UTC-8".                                                 | UNSPECIFIED, COUNT      |
| hour                       | L'ora UTC del completamento automatico o dei completamenti automatici.                                                                                           | UNSPECIFIED, COUNT      |
| language                   | Il linguaggio di programmazione utilizzato.                                                                                                                      | UNSPECIFIED, COUNT      |
| ide                        | L'IDE utilizzato.                                                                                                                                                | UNSPECIFIED, COUNT      |
| version                    | Versione dell'estensione/plugin (language-server), ad es. `1.48.x`                                                                                               | UNSPECIFIED, COUNT      |
| num\_acceptances           | Il numero di volte in cui l'utente ha accettato un completamento automatico. Questo accade quando l'utente scrive del codice, vede del testo grigio e preme tab. | SUM, MAX, MIN, AVG      |
| num\_lines\_accepted       | Righe di codice accettate dal completamento automatico.                                                                                                          | SUM, MAX, MIN, AVG      |
| num\_bytes\_accepted       | Byte accettati dal completamento automatico.                                                                                                                     | SUM, MAX, MIN, AVG      |
| distinct\_users            | Utenti distinti.                                                                                                                                                 | UNSPECIFIED, COUNT      |
| distinct\_developer\_days  | Tuple distinte (utente, giorno).                                                                                                                                 | UNSPECIFIED, COUNT      |
| distinct\_developer\_hours | Tuple distinte (utente, ora del giorno).                                                                                                                         | UNSPECIFIED, COUNT      |

<div id="chat-data">
  ### Dati della chat
</div>

Si noti che tutti i dati forniti nell'API dei dati della chat si riferiscono alle risposte del modello di chat, non alle domande degli utenti.

| **Nome del campo**         | **Descrizione**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | **Aggregazioni valide** |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| api\_key                   | Un hash della API key dell'utente                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | UNSPECIFIED, COUNT      |
| model\_id                  | L'ID del modello di chat, impostato al momento della distribuzione.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | UNSPECIFIED, COUNT      |
| date                       | La data UTC della risposta della chat.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | UNSPECIFIED, COUNT      |
| date UTC-x                 | La data della risposta della chat, con un offset del fuso orario. Per esempio, PST sarebbe "date UTC-8".                                                                                                                                                                                                                                                                                                                                                                                                                 | UNSPECIFIED, COUNT      |
| ide                        | L'IDE in uso                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | UNSPECIFIED, COUNT      |
| version                    | Versione dell'estensione/plugin (language-server), ad es. `1.48.x`                                                                                                                                                                                                                                                                                                                                                                                                                                                       | UNSPECIFIED, COUNT      |
| latest\_intent\_type       | Indica se la risposta del modello viene generata da una code lens o da una chat normale. Le chat normali corrispondono a:<br /><br />CHAT\_INTENT\_GENERIC<br /><br />mentre le code lens corrispondono a uno dei seguenti valori:<br /><br />CHAT\_INTENT\_FUNCTION\_EXPLAIN<br />CHAT\_INTENT\_FUNCTION\_DOCSTRING<br />CHAT\_INTENT\_FUNCTION\_REFACTOR<br />CHAT\_INTENT\_CODE\_BLOCK\_EXPLAIN<br />CHAT\_INTENT\_CODE\_BLOCK\_REFACTOR<br />CHAT\_INTENT\_PROBLEM\_EXPLAIN<br />CHAT\_INTENT\_FUNCTION\_UNIT\_TESTS | UNSPECIFIED, COUNT      |
| num\_chats\_received       | Numero di messaggi di chat inviati da Devin Desktop all'utente.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | SUM, MAX, MIN, AVG      |
| chat\_accepted             | Vero se un blocco di codice è stato inviato nella risposta della chat di Devin Desktop e si fa clic sul pulsante Thumbs up.                                                                                                                                                                                                                                                                                                                                                                                              | SUM, COUNT              |
| chat\_inserted\_at\_cursor | Vero se un blocco di codice è stato inviato nella risposta della chat di Devin Desktop e si fa clic sul pulsante "Insert".                                                                                                                                                                                                                                                                                                                                                                                               | SUM, COUNT              |
| chat\_applied              | Vero se un blocco di codice è stato inviato nella risposta della chat di Devin Desktop e si fa clic sul pulsante "Apply Diff".                                                                                                                                                                                                                                                                                                                                                                                           | SUM, COUNT              |
| chat\_loc\_used            | Righe di codice utilizzate, se un blocco di codice è stato inviato nella chat di Devin Desktop e viene premuto uno dei pulsanti "Insert", "Copy" o "Apply Diff".                                                                                                                                                                                                                                                                                                                                                         | SUM, MAX, MIN, AVG      |

<div id="command-data">
  ### Dati del comando
</div>

Nota che la sorgente dati del comando contiene **tutti** i comandi, inclusi quelli rifiutati. Il campo "accepted" può essere usato per filtrare solo i comandi accettati.

| **Nome del campo** | **Descrizione**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | **Aggregazioni valide** |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| api\_key           | Un hash dell'API key dell'utente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | UNSPECIFIED, COUNT      |
| date               | La data UTC del comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | UNSPECIFIED, COUNT      |
| timestamp          | Il timestamp UTC del comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | UNSPECIFIED, COUNT      |
| language           | Il linguaggio di programmazione utilizzato.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | UNSPECIFIED, COUNT      |
| ide                | L'IDE utilizzato.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | UNSPECIFIED, COUNT      |
| version            | Versione dell'estensione/plugin (language-server), ad es. `1.48.x`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | UNSPECIFIED, COUNT      |
| command\_source    | Il motivo per cui il comando è stato attivato. I valori validi sono:<br /><br />COMMAND\_REQUEST\_SOURCE\_LINE\_HINT\_CODE\_LENS<br />COMMAND\_REQUEST\_SOURCE\_DEFAULT<br />COMMAND\_REQUEST\_SOURCE\_RIGHT\_CLICK\_REFACTOR<br />COMMAND\_REQUEST\_SOURCE\_FUNCTION\_CODE\_LENS<br />COMMAND\_REQUEST\_SOURCE\_FOLLOWUP<br />COMMAND\_REQUEST\_SOURCE\_CLASS\_CODE\_LENS<br />COMMAND\_REQUEST\_SOURCE\_PLAN<br />COMMAND\_REQUEST\_SOURCE\_SELECTION\_HINT\_CODE\_LENS<br /><br />COMMAND\_REQUEST\_SOURCE\_DEFAULT corrisponde al normale utilizzo dei comandi. | UNSPECIFIED, COUNT      |
| provider\_source   | Determina se il comando è stato attivato in modalità generazione o modifica. I valori validi sono: PROVIDER\_SOURCE\_COMMAND\_GENERATE PROVIDER\_SOURCE\_COMMAND\_EDIT                                                                                                                                                                                                                                                                                                                                                                                              | UNSPECIFIED, COUNT      |
| lines\_added       | Numero di righe di codice aggiunte dal comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | SUM, MAX, MIN, AVG      |
| lines\_removed     | Numero di righe di codice rimosse dal comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | SUM, MAX, MIN, AVG      |
| bytes\_added       | Numero di byte aggiunti dal comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | SUM, MAX, MIN, AVG      |
| bytes\_removed     | Numero di byte rimossi dal comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | SUM, MAX, MIN, AVG      |
| selection\_lines   | Numero di righe di codice selezionate dal comando. Per le generazioni, dovrebbe essere sempre zero.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | SUM, MAX, MIN, AVG      |
| selection\_bytes   | Numero di byte selezionati dal comando. Per le generazioni, dovrebbe essere sempre zero.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | SUM, MAX, MIN, AVG      |
| accepted           | Indica se il comando è stato accettato.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | SUM, COUNT              |

<div id="pcw-data">
  ### Dati PCW
</div>

<div id="valid-selections">
  #### Selezioni valide
</div>

| **Nome campo**                   | **Descrizione**                                                                                                                                                                                                                                                                                                             | **Aggregazioni valide** |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| percent\_code\_written           | Percentuale di codice scritto. Calcolata come (numero di byte Codeium generati) / (numero di byte Codeium generati + numero di byte generati dall'utente). Questa metrica può presentare un'elevata variabilità nell'arco della stessa giornata o tra utenti diversi, quindi consigliamo di aggregarla su base settimanale. | UNSPECIFIED             |
| codeium\_bytes                   | numero totale di byte Codeium, pari a codeium\_bytes\_by\_autocomplete + codeium\_bytes\_by\_command                                                                                                                                                                                                                        | UNSPECIFIED             |
| user\_bytes                      | numero totale di byte generati dall'utente                                                                                                                                                                                                                                                                                  | UNSPECIFIED             |
| total\_bytes                     | codeium\_bytes + user\_bytes                                                                                                                                                                                                                                                                                                | UNSPECIFIED             |
| codeium\_bytes\_by\_autocomplete | numero totale di byte Codeium generati dal completamento automatico                                                                                                                                                                                                                                                         | UNSPECIFIED             |
| codeium\_bytes\_by\_command      | numero totale di byte Codeium generati dal comando                                                                                                                                                                                                                                                                          | UNSPECIFIED             |

<div id="cascade-data">
  ### Dati di Cascade
</div>

L’origine dati Cascade contiene una voce per ogni messaggio inviato a Cascade.

<Note>Per accedere a tutti i campi elencati di seguito, assicurati di utilizzare la versione 1.11.2 o successiva.</Note>

| **Nome campo**      | **Descrizione**                                                                                                                                                                                                                       | **Aggregazioni valide**         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| api\_key            | L'hash dell'API key dell'utente.                                                                                                                                                                                                      | UNSPECIFIED, COUNT              |
| date                | La data UTC del comando.                                                                                                                                                                                                              | UNSPECIFIED, COUNT              |
| prompts\_used       | Il numero di crediti prompt utilizzati nel prompt inviato a Cascade, restituito in centesimi. Per esempio, 0,25 crediti viene restituito come 25 e 1 credito viene restituito come 100.                                               | UNSPECIFIED, SUM, AVG, MIN, MAX |
| flex\_credits\_used | Il numero di crediti aggiuntivi/condivisi utilizzati, sul totale di prompts\_used, in un prompt inviato a Cascade, restituito in centesimi. Per esempio, 0,25 crediti viene restituito come 25 e 1 credito viene restituito come 100. | UNSPECIFIED, SUM, AVG, MIN, MAX |
| model               | Il modello utilizzato per il messaggio inviato a Cascade.                                                                                                                                                                             | UNSPECIFIED, COUNT              |
| metadata            | Un oggetto contenente metadati relativi all'ambiente di sviluppo. I campi attualmente valorizzati includono: ideVersion                                                                                                               | UNSPECIFIED, COUNT              |

<div id="valid-filters">
  #### Filtri validi
</div>

|                |                                                                    |                   |
| -------------- | ------------------------------------------------------------------ | ----------------- |
| **Nome campo** | **Descrizione**                                                    | **Alcuni esempi** |
| api\_key       | L'hash della API key dell'utente.                                  |                   |
| language       | Il linguaggio di programmazione utilizzato.                        | KOTLIN, GO, JAVA  |
| ide            | L'IDE utilizzato.                                                  | jetbrains, vscode |
| version        | Versione dell'estensione/plugin (language-server), ad es. `1.48.x` | 1.28.0, 130.0     |

Per filtrare per data, usa start\_timestamp e end\_timestamp, che devono essere nel formato RFC 3339 (ad es. 2023-01-01T00:00:00Z, come nell'esempio seguente).

<div id="examples">
  ## Esempi
</div>

<div id="user-data">
  ### Dati utente
</div>

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": SERVICE_KEY,
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
       {
          "field": "num_acceptances",
          "name": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "hour",
          "filter": "QUERY_FILTER_GE",
          "value": "2024-01-01"
        },
        {
          "name": "hour",
          "filter": "QUERY_FILTER_LE",
          "value": "2024-02-01"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

Questa query calcola la percentuale complessiva di codice scritto nel mese di gennaio 2024. Risposta di esempio (JSON formattato per migliorarne la leggibilità):

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "num_acceptances": "125",
            "num_lines_accepted": "863"
          }
        }
      ]
    }
  ]
}
```

<div id="chat-data">
  ### Dati della chat
</div>

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": SERVICE_KEY,
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_CHAT_DATA",
      "selections": [
        {
          "field": "chat_loc_used",
          "name": "chat_loc_used",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "latest_intent_type",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "CHAT_INTENT_FUNCTION_DOCSTRING"
        }
      ],
      "aggregations": [
        {
          "field": "ide",
          "name": "ide"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

Questa query mostra il numero di righe di codice accettate tramite la code lens "Generate Docstring" dall'inizio, raggruppate per IDE.

Risposta di esempio:

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "chat_loc_used": "74",
            "ide": "jetbrains"
          },
        },
        {
          "item": {
            "chat_loc_used":"41",
            "ide":"vscode"
          },
        }
      ]
    }
  ]
}
```

<div id="command-data">
  ### Dati del comando
</div>

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
 "service_key": SERVICE_KEY,
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_COMMAND_DATA",
     "selections": [
        {
          "field": "lines_added",
          "name": "lines_added",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        },
        {
          "field": "lines_removed",
          "name": "lines_removed",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        }
      ],
      "filters": [
        {
          "name": "provider_source",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "PROVIDER_SOURCE_COMMAND_EDIT"
        },
        {
          "name": "accepted",
          "filter": "QUERY_FILTER_EQUAL",
          "value": "true"
        }
      ],
      "aggregations": [
        {
          "field": "language",
          "name": "language"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

Questa query recupera, per linguaggio di programmazione, il numero di righe aggiunte e rimosse dai comandi "edit".

Risposta di esempio:

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "language": "SHELL",
            "lines_added": "5",
            "lines_removed": "3"
          }
        },
        {
          "item": {
            "language": "GO",
            "lines_added": "31",
            "lines_removed": "27"
          }
        },
        {
          "item": {
            "language": "PYTHON",
            "lines_added": "21",
            "lines_removed": "5"
          }
        },
        {
          "item": {
            "language": "UNSPECIFIED",
            "lines_added": "91",
            "lines_removed": "71"
          }
        },
        {
          "item": {
            "language": "STARLARK",
            "lines_added": "13",
            "lines_removed": "1"
          }
        }
      ]
    }
  ]
}
```

<div id="pcw-data">
  ### Dati PCW
</div>

```sh theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
    "service_key": SERVICE_KEY,
    "start_timestamp": "2024-01-01T00:00:00Z",
    "end_timestamp": "2024-12-22T00:00:00Z"
    "query_requests": [
    {
       "data_source": "QUERY_DATA_SOURCE_PCW_DATA",
       "selections": [
          {
             "field": "percent_code_written",
             "name": "percent_code_written"
          },
          {
             "field": "codeium_bytes",
             "name": "codeium_bytes"
          },
          {
             "field": "total_bytes",
             "name": "total_bytes"
          },
          {
             "field": "codeium_bytes_by_autocomplete",
            "name": "codeium_bytes_by_autocomplete"
          },
          {
             "field": "codeium_bytes_by_command",
             "name": "codeium_bytes_by_command"
          }
       ],
     "filters": [
         {
            "filter": "QUERY_FILTER_EQUAL",
            "name": "language",
            "value": "GO"
         }
      ]
    }
  ],
}' \
https: //server.codeium.com/api/v1/Analytics
```

Questa query recupera i dati PCW (percentuale di codice scritto), insieme ai byte filtrati per il linguaggio Go.

Esempio di risposta:

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
         {
            "item": {
               "codeium_bytes": "6018",
               "codeium_bytes_by_autocomplete": "4593",
               "codeium_bytes_by_command": "1425",
               "percent_code_written": "0.61",
               "total_bytes": "9900"
             }
         }
     ]
   }
  ]
}
```

<div id="query-debugging">
  ## Debug delle query
</div>

A partire dalla versione 1.10.0, le query non valide restituiscono un messaggio di errore. Questa sezione raccoglie alcuni messaggi di errore comuni, il loro significato e come eseguire il debug delle query corrispondenti.

<table>
  <thead>
    <tr>
      <th>Messaggio di errore</th>
      <th>Spiegazione</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>at least one field or aggregation is required</td>
      <td>Non è stata rilevata alcuna selezione o aggregazione: assicurati che la richiesta della query ne includa almeno una.</td>
    </tr>

    <tr>
      <td>invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM</td>
      <td>Una delle selezioni usa una funzione di aggregazione non valida. In questo caso, è stato usato SUM sul campo "ide", ma questo campo supporta solo COUNT e UNSPECIFIED.</td>
    </tr>

    <tr>
      <td>invalid query table: QUERY\_DATA\_SOURCE\_UNSPECIFIED</td>
      <td>Probabilmente c'è un errore di battitura nel campo data\_source; verificane l'ortografia.</td>
    </tr>

    <tr>
      <td>all selection fields should have an aggregation function, or none of them should</td>

      <td>
        Se sono presenti più campi di selezione, tutti devono contenere un aggregation\_function oppure nessuno deve contenerlo. Per esempio, questa selezione non è valida perché num\_acceptances viene sommato, mentre num\_lines\_accepted no:

        ```json theme={null}
        "selections": [
          {
            "field": "num_acceptances",
            "name": "total_acceptances",
            "aggregation_function": "QUERY_AGGREGATION_SUM"
          },
          {
            "field": "num_lines_accepted",
            "name": "total_lines_accepted",
            "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
          }
        ]
        ```

        Nota: PCW è sempre considerato aggregato. Se non viene scelto esplicitamente alcun aggregation\_function, viene considerato non specificato. Se vuoi ottenere informazioni su entrambi questi campi, usa due query separate.
      </td>
    </tr>

    <tr>
      <td>invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM</td>
      <td>Non tutti i campi supportano tutte le funzioni di aggregazione; consulta la sezione dei campi disponibili per vedere le corrispondenze. In questo caso, la query usa la funzione di aggregazione QUERY\_AGGREGATION\_SUM con il campo "ide", il che non è valido.</td>
    </tr>

    <tr>
      <td>tried to aggregate on a distinct field: distinct\_developer\_days. Consider aggregating on the non-distinct fields instead: \[api\_key date]</td>

      <td>
        I campi con il pattern "distinct\_\*" non possono comparire nella sezione aggregations; il messaggio di errore suggerisce invece uno o più campi alternativi su cui aggregare. Quindi, invece di:

        ```json theme={null}
        "aggregations": [
          {
            "field": "distinct_developer_days",
            "name": "distinct_developer_days"
          }
        ]
        ```

        Prova:

        ```json theme={null}
        "aggregations": [
          {
            "field": "api_key",
            "name": "api_key"
          },
          {
            "field": "date",
            "name": "date"
          }
        ]
        ```
      </td>
    </tr>

    <tr>
      <td>duplicate field alias for selection/aggregation: num\_acceptances</td>
      <td>Tutte le selezioni e le aggregazioni devono avere un nome diverso. Tieni presente che, se il nome non è specificato, per default viene impostato su \<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME>.</td>
    </tr>

    <tr>
      <td>invalid group name: GroupName</td>
      <td>Il group con il nome specificato non è stato trovato; verificane l'ortografia.</td>
    </tr>
  </tbody>
</table>