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

# Consulta personalizada de Custom Analytics

> Consulta flexível de análises com seleções, filtros e agregações personalizadas para dados de preenchimento automático, chat, comando e PCW.

<div id="overview">
  ## Visão geral
</div>

A API Custom Analytics permite consultas flexíveis em dados de preenchimento automático, chat e comandos, com seleções, filtros, agregações e ordenações personalizáveis.

<div id="request">
  ## Requisição
</div>

<ParamField body="service_key" type="string" required>
  Sua chave de serviço com permissão "Analytics Read"
</ParamField>

<ParamField body="group_name" type="string">
  Filtra os resultados para usuários em um grupo específico (opcional)
</ParamField>

<ParamField body="query_requests" type="array" required>
  Array de objetos de requisição de consulta que definem os dados a recuperar

  <Expandable title="Objeto de requisição de consulta">
    <ParamField body="data_source" type="string" required>
      Fonte de dados a consultar. Opções:

      * `QUERY_DATA_SOURCE_USER_DATA` - Dados de preenchimento automático
      * `QUERY_DATA_SOURCE_CHAT_DATA` - Dados de chat
      * `QUERY_DATA_SOURCE_COMMAND_DATA` - Dados de comando
      * `QUERY_DATA_SOURCE_PCW_DATA` - Dados de Percent Code Written
    </ParamField>

    <ParamField body="selections" type="array" required>
      Array de seleções de campos a recuperar

      <Expandable title="Objeto de seleção">
        <ParamField body="field" type="string" required>
          Nome do campo a selecionar (consulte a seção Campos disponíveis)
        </ParamField>

        <ParamField body="name" type="string">
          Alias do campo. Se não for especificado, o padrão será `{aggregation_function}_{field_name}` (em minúsculas)
        </ParamField>

        <ParamField body="aggregation_function" type="string">
          Função de agregação a aplicar:

          * `QUERY_AGGREGATION_UNSPECIFIED` (padrão)
          * `QUERY_AGGREGATION_COUNT`
          * `QUERY_AGGREGATION_SUM`
          * `QUERY_AGGREGATION_AVG`
          * `QUERY_AGGREGATION_MAX`
          * `QUERY_AGGREGATION_MIN`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="filters" type="array">
      Array de filtros a aplicar

      <Expandable title="Objeto de filtro">
        <ParamField body="name" type="string" required>
          Nome do campo usado no filtro
        </ParamField>

        <ParamField body="filter" type="string" required>
          Operação de filtro:

          * `QUERY_FILTER_EQUAL`
          * `QUERY_FILTER_NOT_EQUAL`
          * `QUERY_FILTER_GREATER_THAN`
          * `QUERY_FILTER_LESS_THAN`
          * `QUERY_FILTER_GE` (maior ou igual a)
          * `QUERY_FILTER_LE` (menor ou igual a)
        </ParamField>

        <ParamField body="value" type="string" required>
          Valor para comparação
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="aggregations" type="array">
      Array de agregações para agrupar os resultados

      <Expandable title="Objeto de agregação">
        <ParamField body="field" type="string" required>
          Nome do campo para agrupamento
        </ParamField>

        <ParamField body="name" type="string" required>
          Alias do campo de agregação
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<div id="query-request-structure">
  ## Estrutura da requisição de consulta
</div>

Cada objeto de requisição de consulta contém:

* **data\_source** (obrigatório): Fonte de dados a consultar
* **selections** (obrigatório): Array de campos selecionados para recuperar
* **filters** (opcional): Array de filtros a aplicar
* **aggregations** (opcional): Array de agregações para agrupamento

<div id="selections">
  ## Seleções
</div>

As seleções definem quais campos recuperar e como agregá-los.

* **field** (obrigatório): Nome do campo a ser selecionado
* **name** (opcional): Alias do campo
* **aggregation\_function** (opcional): Função de agregação a ser aplicada

<div id="selection-example">
  ### Exemplo de seleção
</div>

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

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

Os filtros restringem os dados aos elementos que atendem a critérios específicos.

* **name** (obrigatório): Nome do campo usado para filtrar
* **filter** (obrigatório): Operação de filtro
* **value** (obrigatório): Valor de comparação

<div id="filter-example">
  ### Exemplo de filtro
</div>

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

<div id="aggregations">
  ## Agregações
</div>

As agregações agrupam os dados com base nos critérios especificados.

* **field** (obrigatório): Nome do campo pelo qual agrupar
* **name** (obrigatório): Alias do campo de agregação

<div id="aggregation-example">
  ### Exemplo de agregação
</div>

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

<div id="available-fields">
  ## Campos disponíveis
</div>

<div id="user-data">
  ### Dados do usuário
</div>

Todos os dados do usuário são agregados por usuário, por hora.

| Nome do campo              | Descrição                                                           | Agregações válidas |
| -------------------------- | ------------------------------------------------------------------- | ------------------ |
| `api_key`                  | hash da Chave de API do usuário                                     | UNSPECIFIED, COUNT |
| `date`                     | Data UTC do preenchimento automático                                | UNSPECIFIED, COUNT |
| `date UTC-x`               | Data com deslocamento de fuso horário (e.g., "date UTC-8" para PST) | UNSPECIFIED, COUNT |
| `hour`                     | Hora UTC do preenchimento automático                                | UNSPECIFIED, COUNT |
| `language`                 | Linguagem de programação                                            | UNSPECIFIED, COUNT |
| `ide`                      | IDE em uso                                                          | UNSPECIFIED, COUNT |
| `version`                  | Versão da extensão/plugin (language-server), e.g. `1.48.x`          | UNSPECIFIED, COUNT |
| `num_acceptances`          | Número de sugestões de preenchimento automático aceitas             | SUM, MAX, MIN, AVG |
| `num_lines_accepted`       | Linhas de código aceitas                                            | SUM, MAX, MIN, AVG |
| `num_bytes_accepted`       | Bytes aceitos                                                       | SUM, MAX, MIN, AVG |
| `distinct_users`           | Usuários distintos                                                  | UNSPECIFIED, COUNT |
| `distinct_developer_days`  | Tuplas distintas de (usuário, dia)                                  | UNSPECIFIED, COUNT |
| `distinct_developer_hours` | Tuplas distintas de (usuário, hora)                                 | UNSPECIFIED, COUNT |

<div id="chat-data">
  ### Dados de chat
</div>

<Info>Os dados de chat são separados dos dados do Cascade e representam o uso dos nossos plugins legados, sem agentes</Info>

Todos os Dados de chat representam respostas do modelo de chat, não perguntas do usuário.

| Nome do campo             | Descrição                                                    | Agregações válidas |
| ------------------------- | ------------------------------------------------------------ | ------------------ |
| `api_key`                 | Hash da Chave de API do usuário                              | UNSPECIFIED, COUNT |
| `model_id`                | ID do modelo de chat                                         | UNSPECIFIED, COUNT |
| `date`                    | Data em UTC da resposta do chat                              | UNSPECIFIED, COUNT |
| `date UTC-x`              | Data com deslocamento de fuso horário                        | UNSPECIFIED, COUNT |
| `ide`                     | IDE em uso                                                   | UNSPECIFIED, COUNT |
| `version`                 | Versão da extensão/plugin (language-server), e.g. `1.48.x`   | UNSPECIFIED, COUNT |
| `latest_intent_type`      | Tipo de intenção do chat (consulte Tipos de intenção abaixo) | UNSPECIFIED, COUNT |
| `num_chats_received`      | Número de mensagens de chat recebidas                        | SUM, MAX, MIN, AVG |
| `chat_accepted`           | Se o chat foi aceito (curtida)                               | SUM, COUNT         |
| `chat_inserted_at_cursor` | Se o botão "Insert" foi clicado                              | SUM, COUNT         |
| `chat_applied`            | Se o botão "Apply Diff" foi clicado                          | SUM, COUNT         |
| `chat_loc_used`           | Linhas de código aproveitadas do chat                        | SUM, MAX, MIN, AVG |

<div id="chat-intent-types">
  #### Tipos de intenção de chat
</div>

* `CHAT_INTENT_GENERIC` - Chat normal
* `CHAT_INTENT_FUNCTION_EXPLAIN` - CodeLens de explicação da função
* `CHAT_INTENT_FUNCTION_DOCSTRING` - CodeLens de docstring da função
* `CHAT_INTENT_FUNCTION_REFACTOR` - CodeLens de refatoração da função
* `CHAT_INTENT_CODE_BLOCK_EXPLAIN` - CodeLens de explicação do bloco de código
* `CHAT_INTENT_CODE_BLOCK_REFACTOR` - CodeLens de refatoração do bloco de código
* `CHAT_INTENT_PROBLEM_EXPLAIN` - CodeLens de explicação do problema
* `CHAT_INTENT_FUNCTION_UNIT_TESTS` - CodeLens de testes unitários da função

<div id="command-data">
  ### dados de comando
</div>

Os dados de comando incluem todos os comandos, inclusive os recusados. Use o campo `accepted` para filtrar apenas os comandos aceitos.

| Nome do campo     | Descrição                                                            | Agregações válidas |
| ----------------- | -------------------------------------------------------------------- | ------------------ |
| `api_key`         | Hash da Chave de API do usuário                                      | UNSPECIFIED, COUNT |
| `date`            | Data UTC do comando                                                  | UNSPECIFIED, COUNT |
| `timestamp`       | Carimbo de data/hora UTC do comando                                  | UNSPECIFIED, COUNT |
| `language`        | Linguagem de programação                                             | UNSPECIFIED, COUNT |
| `ide`             | IDE em uso                                                           | UNSPECIFIED, COUNT |
| `version`         | Versão da extensão/plugin (language-server), por exemplo `1.48.x`    | UNSPECIFIED, COUNT |
| `command_source`  | Origem do acionamento do comando (consulte origem do comando abaixo) | UNSPECIFIED, COUNT |
| `provider_source` | Modo de geração ou edição                                            | UNSPECIFIED, COUNT |
| `lines_added`     | Linhas de código adicionadas                                         | SUM, MAX, MIN, AVG |
| `lines_removed`   | Linhas de código removidas                                           | SUM, MAX, MIN, AVG |
| `bytes_added`     | Bytes adicionados                                                    | SUM, MAX, MIN, AVG |
| `bytes_removed`   | Bytes removidos                                                      | SUM, MAX, MIN, AVG |
| `selection_lines` | Linhas selecionadas (zero para gerações)                             | SUM, MAX, MIN, AVG |
| `selection_bytes` | Bytes selecionados (zero para gerações)                              | SUM, MAX, MIN, AVG |
| `accepted`        | Indica se o comando foi aceito                                       | SUM, COUNT         |

<div id="command-sources">
  #### Origens do comando
</div>

* `COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_DEFAULT` - Uso comum do comando
* `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">
  #### Origens do provedor
</div>

* `PROVIDER_SOURCE_COMMAND_GENERATE` - Modo de geração
* `PROVIDER_SOURCE_COMMAND_EDIT` - Modo de edição

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

Dados de Percentual de Código Escrito com rastreamento separado para contribuições de preenchimento automático e de comando.

| Nome do campo                   | Descrição                                                      | Agregações válidas |
| ------------------------------- | -------------------------------------------------------------- | ------------------ |
| `percent_code_written`          | Calculado como codeium\_bytes / (codeium\_bytes + user\_bytes) | UNSPECIFIED        |
| `codeium_bytes`                 | Total de bytes gerados pelo Codeium                            | UNSPECIFIED        |
| `user_bytes`                    | Total de bytes escritos pelo usuário                           | UNSPECIFIED        |
| `total_bytes`                   | codeium\_bytes + user\_bytes                                   | UNSPECIFIED        |
| `codeium_bytes_by_autocomplete` | Bytes do Codeium provenientes do preenchimento automático      | UNSPECIFIED        |
| `codeium_bytes_by_command`      | Bytes do Codeium provenientes de comandos                      | UNSPECIFIED        |

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

| Nome do campo | Descrição                                                         | Exemplos          |
| ------------- | ----------------------------------------------------------------- | ----------------- |
| `language`    | Linguagem de programação                                          | KOTLIN, GO, JAVA  |
| `ide`         | IDE em uso                                                        | jetbrains, vscode |
| `version`     | Versão da extensão/plugin (language-server), por exemplo `1.48.x` | 1.28.0, 130.0     |

Para filtrar por data em consultas de PCW, use `start_timestamp` e `end_timestamp` no corpo principal da requisição.

<div id="example-requests">
  ## Exemplos de requisições
</div>

<div id="user-data-example">
  ### Exemplo de dados do usuário
</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">
  ### Exemplo de dados 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">
  ### Exemplo de dados de comando
</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">
  ### Exemplo de dados de 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">
  ## Resposta
</div>

<ResponseField name="queryResults" type="array">
  Array de resultados da consulta, um para cada requisição de consulta

  <ResponseField name="responseItems" type="array">
    Array de itens de resultado

    <ResponseField name="item" type="object">
      Objeto que contém os campos selecionados e seus valores
    </ResponseField>
  </ResponseField>
</ResponseField>

<div id="example-responses">
  ### Exemplos de resposta
</div>

<div id="user-data-response">
  #### Resposta de dados do usuário
</div>

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

<div id="chat-data-response">
  #### Resposta de dados 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">
  #### Resposta de dados de comando
</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">
  #### Resposta de dados de 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">
  ## Notas importantes
</div>

* O PCW (Percent Code Written) apresenta alta variabilidade em um mesmo dia ou entre usuários — agregue ao longo de semanas para obter melhores insights
* Todos os campos de seleção devem ter funções de agregação, ou nenhum deve ter (não é possível misturar)
* Campos com o padrão "distinct\_\*" não podem ser usados em agregações
* Os aliases dos campos devem ser exclusivos em todas as seleções e agregações
* Se nenhuma função de agregação for especificada, o padrão será UNSPECIFIED