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

# Requête d’analyse personnalisée

> Interrogation flexible des données d’analyse avec sélections, filtres et agrégations personnalisés pour les données d’autocomplétion, de chat, de Command et de PCW.

<div id="overview">
  ## Vue d’ensemble
</div>

L’API d’analyse personnalisée permet d’interroger de manière flexible les données d’autocomplétion, de chat et de Command, avec des sélections, filtres, agrégations et tris personnalisables.

<div id="request">
  ## Requête
</div>

<ParamField body="service_key" type="string" required>
  Votre clé de service avec les autorisations « Analytics Read »
</ParamField>

<ParamField body="group_name" type="string">
  Filtrer les résultats pour n’inclure que les utilisateurs d’un groupe spécifique (facultatif)
</ParamField>

<ParamField body="query_requests" type="array" required>
  Tableau d’objets de requête définissant les données à récupérer

  <Expandable title="Objet de requête">
    <ParamField body="data_source" type="string" required>
      Source de données à interroger. Options :

      * `QUERY_DATA_SOURCE_USER_DATA` - Données utilisateur
      * `QUERY_DATA_SOURCE_CHAT_DATA` - Données de chat
      * `QUERY_DATA_SOURCE_COMMAND_DATA` - Données de Command
      * `QUERY_DATA_SOURCE_PCW_DATA` - Données de pourcentage de code écrit
    </ParamField>

    <ParamField body="selections" type="array" required>
      Tableau des champs à récupérer

      <Expandable title="Objet de sélection">
        <ParamField body="field" type="string" required>
          Nom du champ à sélectionner (voir la section Champs disponibles)
        </ParamField>

        <ParamField body="name" type="string">
          Alias du champ. S’il n’est pas spécifié, la valeur par défaut est `{aggregation_function}_{field_name}` (en minuscules)
        </ParamField>

        <ParamField body="aggregation_function" type="string">
          Fonction d’agrégation à appliquer :

          * `QUERY_AGGREGATION_UNSPECIFIED` (par défaut)
          * `QUERY_AGGREGATION_COUNT`
          * `QUERY_AGGREGATION_SUM`
          * `QUERY_AGGREGATION_AVG`
          * `QUERY_AGGREGATION_MAX`
          * `QUERY_AGGREGATION_MIN`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="filters" type="array">
      Tableau des filtres à appliquer

      <Expandable title="Objet de filtre">
        <ParamField body="name" type="string" required>
          Nom du champ sur lequel filtrer
        </ParamField>

        <ParamField body="filter" type="string" required>
          Opération de filtrage :

          * `QUERY_FILTER_EQUAL`
          * `QUERY_FILTER_NOT_EQUAL`
          * `QUERY_FILTER_GREATER_THAN`
          * `QUERY_FILTER_LESS_THAN`
          * `QUERY_FILTER_GE` (supérieur ou égal à)
          * `QUERY_FILTER_LE` (inférieur ou égal à)
        </ParamField>

        <ParamField body="value" type="string" required>
          Valeur de comparaison
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="aggregations" type="array">
      Tableau des agrégations utilisées pour le regroupement

      <Expandable title="Objet d’agrégation">
        <ParamField body="field" type="string" required>
          Nom du champ de regroupement
        </ParamField>

        <ParamField body="name" type="string" required>
          Alias du champ d’agrégation
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<div id="query-request-structure">
  ## Structure de l’objet de requête
</div>

Chaque objet de requête contient :

* **data\_source** (obligatoire) : source de données à interroger
* **selections** (obligatoire) : tableau des sélections de champs à récupérer
* **filters** (facultatif) : tableau des filtres à appliquer
* **aggregations** (facultatif) : tableau des agrégations à utiliser pour le regroupement

<div id="selections">
  ## Sélections
</div>

Les sélections définissent les champs à récupérer et la manière de les agréger.

* **field** (obligatoire) : Nom du champ à sélectionner
* **name** (facultatif) : Alias du champ
* **aggregation\_function** (facultatif) : Fonction d’agrégation à appliquer

<div id="selection-example">
  ### Exemple de sélection
</div>

```json theme={null}
{
  "field": "num_acceptances",
  "name": "total_acceptances",
  "aggregation_function": "QUERY_AGGREGATION_SUM"
}
```

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

Les filtres permettent de restreindre les données aux éléments qui répondent à des critères spécifiques.

* **name** (obligatoire) : Nom du champ sur lequel appliquer le filtre
* **filter** (obligatoire) : Opération de filtrage
* **value** (obligatoire) : Valeur à laquelle comparer

<div id="filter-example">
  ### Exemple de filtre
</div>

```json theme={null}
{
  "name": "language",
  "filter": "QUERY_FILTER_EQUAL",
  "value": "PYTHON"
}
```

<div id="aggregations">
  ## Agrégations
</div>

Les agrégations regroupent les données selon des critères spécifiés.

* **field** (obligatoire) : Nom du champ selon lequel regrouper
* **name** (obligatoire) : Alias du champ d’agrégation

<div id="aggregation-example">
  ### Exemple d’agrégation
</div>

```json theme={null}
{
  "field": "ide",
  "name": "ide_type"
}
```

<div id="available-fields">
  ## Champs disponibles
</div>

<div id="user-data">
  ### Données utilisateur
</div>

Toutes les données utilisateur sont agrégées par utilisateur, par heure.

| Nom du champ               | Description                                                            | Agrégations valides |
| -------------------------- | ---------------------------------------------------------------------- | ------------------- |
| `api_key`                  | Hachage de la clé API de l’utilisateur                                 | UNSPECIFIED, COUNT  |
| `date`                     | Date UTC de l’autocomplétion                                           | UNSPECIFIED, COUNT  |
| `date UTC-x`               | Date avec décalage de fuseau horaire (p. ex., « date UTC-8 » pour PST) | UNSPECIFIED, COUNT  |
| `hour`                     | Heure UTC de l’autocomplétion                                          | UNSPECIFIED, COUNT  |
| `language`                 | Langage de programmation                                               | UNSPECIFIED, COUNT  |
| `ide`                      | IDE utilisé                                                            | UNSPECIFIED, COUNT  |
| `version`                  | Version de l’extension/du plugin (language-server), p. ex. `1.48.x`    | UNSPECIFIED, COUNT  |
| `num_acceptances`          | Nombre de suggestions d’autocomplétion acceptées                       | SUM, MAX, MIN, AVG  |
| `num_lines_accepted`       | Nombre de lignes de code acceptées                                     | SUM, MAX, MIN, AVG  |
| `num_bytes_accepted`       | Nombre d’octets acceptés                                               | SUM, MAX, MIN, AVG  |
| `distinct_users`           | Nombre d’utilisateurs distincts                                        | UNSPECIFIED, COUNT  |
| `distinct_developer_days`  | Nombre de tuples (utilisateur, jour) distincts                         | UNSPECIFIED, COUNT  |
| `distinct_developer_hours` | Nombre de tuples (utilisateur, heure) distincts                        | UNSPECIFIED, COUNT  |

<div id="chat-data">
  ### Données de chat
</div>

<Info>Les données de chat sont distinctes des données Cascade et correspondent à l’utilisation de nos anciens plugins non agentiques</Info>

Toutes les données de chat correspondent aux réponses du modèle de chat, et non aux questions des utilisateurs.

| Nom du champ              | Description                                                         | Agrégations valides |
| ------------------------- | ------------------------------------------------------------------- | ------------------- |
| `api_key`                 | Hachage de la clé API de l’utilisateur                              | UNSPECIFIED, COUNT  |
| `model_id`                | ID du modèle de chat                                                | UNSPECIFIED, COUNT  |
| `date`                    | Date UTC de la réponse du chat                                      | UNSPECIFIED, COUNT  |
| `date UTC-x`              | Date avec décalage de fuseau horaire                                | UNSPECIFIED, COUNT  |
| `ide`                     | IDE utilisé                                                         | UNSPECIFIED, COUNT  |
| `version`                 | Version de l’extension/du plugin (language-server), p. ex. `1.48.x` | UNSPECIFIED, COUNT  |
| `latest_intent_type`      | Type d’intention du chat (voir Types d’intention ci-dessous)        | UNSPECIFIED, COUNT  |
| `num_chats_received`      | Nombre de messages de chat reçus                                    | SUM, MAX, MIN, AVG  |
| `chat_accepted`           | Indique si le chat a été accepté (pouce levé)                       | SUM, COUNT          |
| `chat_inserted_at_cursor` | Indique si le bouton « Insert » a été cliqué                        | SUM, COUNT          |
| `chat_applied`            | Indique si le bouton « Apply Diff » a été cliqué                    | SUM, COUNT          |
| `chat_loc_used`           | Nombre de lignes de code utilisées depuis le chat                   | SUM, MAX, MIN, AVG  |

<div id="chat-intent-types">
  #### Types d’intention du chat
</div>

* `CHAT_INTENT_GENERIC` - Chat standard
* `CHAT_INTENT_FUNCTION_EXPLAIN` - Code lens d’explication de fonction
* `CHAT_INTENT_FUNCTION_DOCSTRING` - Code lens de docstring de fonction
* `CHAT_INTENT_FUNCTION_REFACTOR` - Code lens de refactorisation de fonction
* `CHAT_INTENT_CODE_BLOCK_EXPLAIN` - Code lens d’explication de bloc de code
* `CHAT_INTENT_CODE_BLOCK_REFACTOR` - Code lens de refactorisation de bloc de code
* `CHAT_INTENT_PROBLEM_EXPLAIN` - Code lens d’explication du problème
* `CHAT_INTENT_FUNCTION_UNIT_TESTS` - Code lens de tests unitaires pour une fonction

<div id="command-data">
  ### Données de Command
</div>

Les données de Command incluent toutes les commandes, y compris celles qui ont été rejetées. Utilisez le champ `accepted` pour filtrer uniquement les commandes acceptées.

| Nom du champ      | Description                                                             | Agrégations valides |
| ----------------- | ----------------------------------------------------------------------- | ------------------- |
| `api_key`         | Hachage de la clé API de l'utilisateur                                  | UNSPECIFIED, COUNT  |
| `date`            | Date UTC de la commande                                                 | UNSPECIFIED, COUNT  |
| `timestamp`       | Horodatage UTC de la commande                                           | UNSPECIFIED, COUNT  |
| `language`        | Langage de programmation                                                | UNSPECIFIED, COUNT  |
| `ide`             | IDE utilisé                                                             | UNSPECIFIED, COUNT  |
| `version`         | Version de l’extension/du plugin (language-server), p. ex. `1.48.x`     | UNSPECIFIED, COUNT  |
| `command_source`  | Source de déclenchement de Command (voir Sources de Command ci-dessous) | UNSPECIFIED, COUNT  |
| `provider_source` | Mode de génération ou d’édition                                         | UNSPECIFIED, COUNT  |
| `lines_added`     | Lignes de code ajoutées                                                 | SUM, MAX, MIN, AVG  |
| `lines_removed`   | Lignes de code supprimées                                               | SUM, MAX, MIN, AVG  |
| `bytes_added`     | Octets ajoutés                                                          | SUM, MAX, MIN, AVG  |
| `bytes_removed`   | Octets supprimés                                                        | SUM, MAX, MIN, AVG  |
| `selection_lines` | Lignes sélectionnées (zéro pour les générations)                        | SUM, MAX, MIN, AVG  |
| `selection_bytes` | Octets sélectionnés (zéro pour les générations)                         | SUM, MAX, MIN, AVG  |
| `accepted`        | Indique si la commande a été acceptée                                   | SUM, COUNT          |

<div id="command-sources">
  #### Origines de Command
</div>

* `COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_DEFAULT` - Usage typique de Command
* `COMMAND_REQUEST_SOURCE_RIGHT_CLICK_REFACTOR`
* `COMMAND_REQUEST_SOURCE_FUNCTION_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_FOLLOWUP`
* `COMMAND_REQUEST_SOURCE_CLASS_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_PLAN`
* `COMMAND_REQUEST_SOURCE_SELECTION_HINT_CODE_LENS`

<div id="provider-sources">
  #### Sources du fournisseur
</div>

* `PROVIDER_SOURCE_COMMAND_GENERATE` - Mode de génération
* `PROVIDER_SOURCE_COMMAND_EDIT` - Mode d’édition

<div id="pcw-data">
  ### Données PCW
</div>

Données sur le pourcentage de code écrit, avec un suivi distinct des contributions de l’autocomplétion et de Command.

| Nom du champ                    | Description                                                   | Agrégations valides |
| ------------------------------- | ------------------------------------------------------------- | ------------------- |
| `percent_code_written`          | Calculé selon codeium\_bytes / (codeium\_bytes + user\_bytes) | UNSPECIFIED         |
| `codeium_bytes`                 | Nombre total d’octets générés par Codeium                     | UNSPECIFIED         |
| `user_bytes`                    | Nombre total d’octets écrits par l’utilisateur                | UNSPECIFIED         |
| `total_bytes`                   | codeium\_bytes + user\_bytes                                  | UNSPECIFIED         |
| `codeium_bytes_by_autocomplete` | Octets Codeium provenant de l’autocomplétion                  | UNSPECIFIED         |
| `codeium_bytes_by_command`      | Octets Codeium provenant de Command                           | UNSPECIFIED         |

<div id="pcw-filters">
  #### Filtres PCW
</div>

| Nom du champ | Description                                                         | Exemples          |
| ------------ | ------------------------------------------------------------------- | ----------------- |
| `language`   | Langage de programmation                                            | KOTLIN, GO, JAVA  |
| `ide`        | IDE utilisé                                                         | jetbrains, vscode |
| `version`    | Version de l’extension/du plugin (language-server), p. ex. `1.48.x` | 1.28.0, 130.0     |

Pour filtrer par date dans les requêtes PCW, utilisez `start_timestamp` et `end_timestamp` dans le corps principal de la requête.

<div id="example-requests">
  ## Exemples de requêtes
</div>

<div id="user-data-example">
  ### Exemple de données utilisateur
</div>

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

<div id="chat-data-example">
  ### Exemple de données de chat
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_CHAT_DATA",
      "selections": [
        {
          "field": "chat_loc_used",
          "name": "lines_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_type"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

<div id="command-data-example">
  ### Exemple de données Command
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_COMMAND_DATA",
      "selections": [
        {
          "field": "lines_added",
          "name": "total_lines_added",
          "aggregation_function": "QUERY_AGGREGATION_SUM"
        },
        {
          "field": "lines_removed",
          "name": "total_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": "programming_language"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

<div id="pcw-data-example">
  ### Exemple de données PCW
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here",
  "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": "pcw"
        },
        {
          "field": "codeium_bytes",
          "name": "ai_bytes"
        },
        {
          "field": "total_bytes",
          "name": "total"
        },
        {
          "field": "codeium_bytes_by_autocomplete",
          "name": "autocomplete_bytes"
        },
        {
          "field": "codeium_bytes_by_command",
          "name": "command_bytes"
        }
      ],
      "filters": [
        {
          "filter": "QUERY_FILTER_EQUAL",
          "name": "language",
          "value": "GO"
        }
      ]
    }
  ]
}' \
https://server.codeium.com/api/v1/Analytics
```

<div id="response">
  ## Réponse
</div>

<ResponseField name="queryResults" type="array">
  Tableau des résultats de requête, un pour chaque requête

  <ResponseField name="responseItems" type="array">
    Tableau des éléments de résultat

    <ResponseField name="item" type="object">
      Objet contenant les champs sélectionnés et leurs valeurs
    </ResponseField>
  </ResponseField>
</ResponseField>

<div id="example-responses">
  ### Exemples de réponses
</div>

<div id="user-data-response">
  #### Réponse de données utilisateur
</div>

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

<div id="chat-data-response">
  #### Réponse des données de chat
</div>

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

<div id="command-data-response">
  #### Réponse de données de Command
</div>

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "programming_language": "PYTHON",
            "total_lines_added": "21",
            "total_lines_removed": "5"
          }
        },
        {
          "item": {
            "programming_language": "GO",
            "total_lines_added": "31",
            "total_lines_removed": "27"
          }
        }
      ]
    }
  ]
}
```

<div id="pcw-data-response">
  #### Réponse de données PCW
</div>

```json theme={null}
{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "ai_bytes": "6018",
            "autocomplete_bytes": "4593",
            "command_bytes": "1425",
            "pcw": "0.61",
            "total": "9900"
          }
        }
      ]
    }
  ]
}
```

<div id="important-notes">
  ## Remarques importantes
</div>

* Le PCW (Percent Code Written) présente une forte variabilité d'un jour à l'autre ou d'un utilisateur à l'autre - agréguez sur plusieurs semaines pour obtenir des résultats plus pertinents
* Tous les champs de sélection doivent soit avoir une fonction d'agrégation, soit n'en avoir aucune (impossible de mélanger)
* Les champs avec le motif "distinct\_\*" ne peuvent pas être utilisés dans des agrégations
* Les alias de champ doivent être uniques dans l'ensemble des sélections et des agrégations
* Si aucune fonction d'agrégation n'est spécifiée, la valeur par défaut est UNSPECIFIED