> ## 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 de Análises (Enterprise SaaS)

> Consulte dados de análises do Devin Desktop pela API, incluindo métricas de autocompletar, chat, comando, Cascade e PCW. Oferece suporte a filtros, agregações e agrupamentos personalizados.

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

O Devin Desktop oferece suporte a uma API para análises personalizadas. Ela permite consultar dados de autocompletar, chat e comandos, com diversos filtros, agrupamentos e agregações.

Fornecemos todos os exemplos em curl; depois, eles podem ser convertidos em requisições HTTP em outras linguagens.

<Note>A API de Análises está disponível nos planos Enterprise</Note>

<div id="user-data-analytics-api-specification">
  ## Especificação da API de análises de dados de usuários
</div>

Os dados da tabela Users na página Teams podem ser obtidos com o seguinte 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**: A chave de serviço — um usuário administrador pode criar uma na seção de chave de serviço da página de Configurações. A função da chave de serviço deve ter as permissões "Teams somente leitura".

**GROUP\_NAME**: O nome de um grupo pelo qual filtrar. Este campo é opcional.

**START\_TIMESTAMP/END\_TIMESTAMP**: Carimbos de data/hora no formato RFC 3339, por exemplo 2023-01-01T00:00:00Z

<div id="example-output">
  #### **Exemplo de saída**
</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">
  ## Especificação da API de análises do Cascade
</div>

Os dados específicos do Cascade exibidos na [página de análises](https://windsurf.com/team/analytics) podem ser consultados pela 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**: A chave de serviço — um usuário administrador pode criar uma nova em [Configurações da equipe](https://windsurf.com/team/settings)

**GROUP\_NAME**: O nome de um grupo para filtrar. Este campo é opcional. Não pode ser definido se emails estiver definido.

**START\_TIMESTAMP/END\_TIMESTAMP**: Timestamps no formato RFC 3339, por exemplo, 2023-01-01T00:00:00Z

**EMAILS**: Uma lista de e-mails para filtrar. Este campo é opcional. Não pode ser definido se group\_name estiver definido.

**IDE\_TYPES**: Uma lista de tipos de IDE para filtrar. Este campo é opcional. Os valores possíveis estão descritos abaixo.

**QUERY\_REQUESTS**: Uma lista de requisições de consulta a serem feitas. Este campo é obrigatório. Os valores possíveis de CASCADE\_DATA\_SOURCE estão descritos abaixo.

<div id="example-query">
  #### Exemplo de consulta
</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">
  ### Tipos de IDE
</div>

Dividimos os dados do Cascade em categorias por tipo de IDE. Se o campo ide\_types for omitido da query, serão retornados dados de todos os tipos. Se você quiser consultar dados de apenas um dos IDEs, pode usar qualquer uma das seguintes opções:

* "editor" para o Devin Desktop Editor
* "jetbrains" para o plugin do JetBrains
* "cli" para o Devin CLI

<Note>Ao filtrar por Devin CLI (`"cli"`), apenas `cascade_runs` retorna dados. As fontes de dados `cascade_lines` e `cascade_tool_usage` não são compatíveis com o Devin CLI e retornarão resultados vazios.</Note>

<div id="cascade-data-sources">
  ### Fontes de dados do Cascade
</div>

Há três valores possíveis para CASCADE\_DATA\_SOURCE

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

Use `cascade&#95;lines` para consultar dados sobre as linhas do Cascade sugeridas e aceitas por dia.

Exemplo de saída:

```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**: O número de linhas sugeridas no dia especificado.
**linesAccepted**: O número de linhas aceitas no dia especificado.

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

Use o cascade\_runs para consultar dados sobre o uso do modelo, o consumo de créditos e o modo.

Exemplo de saída:

```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**: A data da execução.

**model**: O modelo usado na mensagem.

**mode**: O modo da execução. Um entre CONVERSATIONAL\_PLANNER\_MODE\_DEFAULT (no modo de escrita), CONVERSATIONAL\_PLANNER\_MODE\_READ\_ONLY (no modo somente leitura), CONVERSATIONAL\_PLANNER\_MODE\_NO\_TOOL (no modo legado) ou UNKNOWN.

**messagesSent**: O número de mensagens enviadas.

**cascadeId**: O ID da execução. Esse ID pode ser usado para entender quantas conversas distintas foram iniciadas (em vez de quantas vezes o usuário envia uma mensagem).

**promptsUsed**: O número de créditos usados. Esse valor é retornado em centavos. Por exemplo, 0,25 crédito é retornado como 25, e 1 crédito é retornado como 100.

Os dados retornados pela API estão em formato bruto, o que pode explicar eventuais valores "UNKNOWN". Se você usar essa fonte de dados para suas próprias métricas, é recomendável agregar de acordo com as métricas específicas de seu interesse (por exemplo, somar o campo promptsUsed para entender os padrões de uso do usuário, messagesSent para entender o engajamento do usuário etc.), pois é possível que os dados de modo e prompts estejam divididos entre entradas.

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

Use cascade\_tool\_usage para consultar dados de uso de ferramentas. Observe que isso retorna uma contagem agregada do uso de ferramentas no período informado.

Exemplo de saída:

```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**: A ferramenta usada na mensagem.

**count**: O número de vezes que a ferramenta foi usada.

Aqui está um mapa dos enums retornados e seus nomes legíveis, conforme exibidos na UI:

* CODE\_ACTION: 'Editar código'
* VIEW\_FILE: 'Visualizar arquivo'
* RUN\_COMMAND: 'Executar comando'
* FIND: 'Ferramenta Find'
* GREP\_SEARCH: 'Busca grep'
* VIEW\_FILE\_OUTLINE: 'Visualizar estrutura do arquivo'
* MQUERY: 'Riptide'
* LIST\_DIRECTORY: 'Listar diretório'
* MCP\_TOOL: 'Ferramenta MCP'
* PROPOSE\_CODE: 'Propor código'
* SEARCH\_WEB: 'Pesquisar na web'
* MEMORY: 'Memória'
* PROXY\_WEB\_SERVER: 'Pré-visualização no navegador'
* DEPLOY\_WEB\_APP: 'Implantar app web'

<div id="custom-analytics-api-specification">
  ## Especificação da API de Análises Personalizadas
</div>

Certas fontes de dados permitem consultas personalizadas por meio da API de Análises Personalizadas.

**Os esquemas completos de seleções, filtros, agregações e ordenações estão na seção a seguir, em formato JSON. Consultas de exemplo para cada uma das três fontes de dados, assim como dicas de depuração de consultas, estarão no final do documento.**

```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**: selecione USER\_DATA, CHAT\_DATA, COMMAND\_DATA, PCW\_DATA ou CASCADE\_DATA, dependendo de você estar buscando dados de preenchimento automático, chat, Command, PCW ou Cascade.

**SERVICE\_KEY**: A chave de serviço — um usuário administrador pode criar uma nova em [Configurações da equipe](https://windsurf.com/team/settings). A função da chave de serviço deve ter a permissão "Analytics Read".

**GROUP\_NAME**: O nome de um grupo para usar como filtro. Este campo é opcional.

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

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

As seleções são **obrigatórias**. Cada seleção corresponde a um valor que será consultado.

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

**FIELD\_NAME**: O campo que você deseja consultar. Veja a seção Campos disponíveis abaixo.

**NAME**: Um nome alternativo para o campo. Se não for especificado, será a versão em minúsculas de \<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME>, por exemplo sum\_num\_acceptances. Deve ser diferente de todos os outros nomes de campo e agregação.

**AGGREGATION\_FUNCTION**: deve ser um entre UNSPECIFIED, COUNT, SUM, AVG, MAX e MIN. Se "aggregation\_function" não for informado, o valor padrão será UNSPECIFIED.

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

Os filtros são usados para restringir os dados, de modo que contenham apenas elementos que atendam a determinados critérios. Eles são opcionais.

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

**NAME**: O nome do campo que você deseja filtrar. Se o item filtrado for o mesmo que uma Seleção/Aggregação, ele deverá ser igual ao nome do campo/agregação.

**VALUE**: o valor que está sendo comparado.

**FILTER**: Um dos seguintes: EQUAL, NOT\_EQUAL, GREATER\_THAN, LESS\_THAN, GE (maior que ou igual a), LE (menor que ou igual a).

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

As agregações servem para dividir os dados em grupos com base em um critério especificado. Elas são opcionais.

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

FIELD\_NAME: O campo que você deseja consultar. Consulte a seção Campos disponíveis.

NAME: Um alias para o campo. Deve ser diferente de todos os outros nomes de campos e agregações.

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

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

Todos os dados da fonte USER\_DATA são agregados por usuário, por hora.

Observação: PCW (percentual de código escrito) agora tem sua própria tabela e não depende da tabela user\_data.

| **Nome do campo**          | **Descrição**                                                                                                                                                 | **Agregações válidas** |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| api\_key                   | Um hash da chave de API do usuário.                                                                                                                           | UNSPECIFIED, COUNT     |
| date                       | A data em UTC das autocompletações.                                                                                                                           | UNSPECIFIED, COUNT     |
| date UTC-x                 | A data da autocompletação, com um deslocamento de fuso horário. Por exemplo, PST seria "date UTC-8".                                                          | UNSPECIFIED, COUNT     |
| hour                       | A hora em UTC das autocompletações.                                                                                                                           | UNSPECIFIED, COUNT     |
| language                   | A linguagem de programação em uso.                                                                                                                            | UNSPECIFIED, COUNT     |
| ide                        | A IDE em uso.                                                                                                                                                 | UNSPECIFIED, COUNT     |
| version                    | Versão da extensão/plugin (language-server), por exemplo `1.48.x`                                                                                             | UNSPECIFIED, COUNT     |
| num\_acceptances           | O número de vezes que o usuário aceitou uma autocompletação. Isso ocorre quando o usuário escreve algum código, vê um texto em cinza e pressiona a tecla Tab. | SUM, MAX, MIN, AVG     |
| num\_lines\_accepted       | Linhas de código aceitas da autocompletação.                                                                                                                  | SUM, MAX, MIN, AVG     |
| num\_bytes\_accepted       | Bytes aceitos da autocompletação.                                                                                                                             | SUM, MAX, MIN, AVG     |
| distinct\_users            | Usuários distintos.                                                                                                                                           | UNSPECIFIED, COUNT     |
| distinct\_developer\_days  | Tuplas distintas de (usuários, dia).                                                                                                                          | UNSPECIFIED, COUNT     |
| distinct\_developer\_hours | Tuplas distintas de (usuários, hora do dia).                                                                                                                  | UNSPECIFIED, COUNT     |

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

Observe que todos os dados fornecidos na API de dados do chat se referem às respostas do modelo de chat, não às perguntas do usuário.

| **Nome do campo**          | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | **Agregações válidas** |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| api\_key                   | Um hash da Chave de API do usuário                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | UNSPECIFIED, COUNT     |
| model\_id                  | O ID do modelo de chat, definido no momento da implantação.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | UNSPECIFIED, COUNT     |
| date                       | A data UTC da resposta do chat.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | UNSPECIFIED, COUNT     |
| date UTC-x                 | A data da resposta do chat, com um deslocamento de fuso horário. Por exemplo, PST seria "date UTC-8".                                                                                                                                                                                                                                                                                                                                                                                                                      | UNSPECIFIED, COUNT     |
| ide                        | A IDE que estava em uso                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | UNSPECIFIED, COUNT     |
| version                    | Versão da extensão/plugin (language-server), por exemplo `1.48.x`                                                                                                                                                                                                                                                                                                                                                                                                                                                          | UNSPECIFIED, COUNT     |
| latest\_intent\_type       | Indica se a resposta do modelo é gerada a partir de uma lente de código ou de um chat comum. Chats comuns corresponderão a:<br /><br />CHAT\_INTENT\_GENERIC<br /><br />enquanto lentes de código corresponderão a um dos seguintes:<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       | Número de mensagens de chat enviadas do Devin Desktop para o usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | SUM, MAX, MIN, AVG     |
| chat\_accepted             | True se um bloco de código foi enviado na resposta de chat do Devin Desktop e o botão de curtir foi clicado.                                                                                                                                                                                                                                                                                                                                                                                                               | SUM, COUNT             |
| chat\_inserted\_at\_cursor | True se um bloco de código foi enviado na resposta de chat do Devin Desktop e o botão "Insert" foi clicado.                                                                                                                                                                                                                                                                                                                                                                                                                | SUM, COUNT             |
| chat\_applied              | True se um bloco de código foi enviado na resposta de chat do Devin Desktop e o botão "Apply Diff" foi clicado.                                                                                                                                                                                                                                                                                                                                                                                                            | SUM, COUNT             |
| chat\_loc\_used            | Linhas de código usadas, se um bloco de código foi enviado no chat do Devin Desktop e qualquer um dos botões "Insert", "Copy" ou "Apply Diff" tiver sido pressionado.                                                                                                                                                                                                                                                                                                                                                      | SUM, MAX, MIN, AVG     |

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

Observe que a fonte dados de comando contém **todos** os comandos, inclusive os que foram recusados. O campo "accepted" pode ser usado para filtrar apenas os comandos aceitos.

| **Nome do Campo** | **Descrição**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | **Agregações válidas** |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| api\_key          | Um hash da Chave de API do usuário.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | UNSPECIFIED, COUNT     |
| date              | A data UTC do comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | UNSPECIFIED, COUNT     |
| timestamp         | O carimbo de data/hora UTC do comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | UNSPECIFIED, COUNT     |
| language          | A linguagem de programação em uso.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | UNSPECIFIED, COUNT     |
| ide               | A IDE em uso.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | UNSPECIFIED, COUNT     |
| version           | Versão da extensão/plugin (language-server), por exemplo `1.48.x`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | UNSPECIFIED, COUNT     |
| command\_source   | O motivo pelo qual o comando foi acionado. Os valores válidos são:<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 corresponde ao uso típico do comando. | UNSPECIFIED, COUNT     |
| provider\_source  | Determina se o comando foi acionado no modo de geração ou de edição. Os valores válidos são: PROVIDER\_SOURCE\_COMMAND\_GENERATE PROVIDER\_SOURCE\_COMMAND\_EDIT                                                                                                                                                                                                                                                                                                                                                                                           | UNSPECIFIED, COUNT     |
| lines\_added      | Número de linhas de código adicionadas pelo comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | SUM, MAX, MIN, AVG     |
| lines\_removed    | Número de linhas de código removidas pelo comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | SUM, MAX, MIN, AVG     |
| bytes\_added      | Número de bytes adicionados pelo comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | SUM, MAX, MIN, AVG     |
| bytes\_removed    | Número de bytes removidos pelo comando.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | SUM, MAX, MIN, AVG     |
| selection\_lines  | Número de linhas de código selecionadas pelo comando. Deve ser sempre zero para gerações.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | SUM, MAX, MIN, AVG     |
| selection\_bytes  | Número de bytes selecionados pelo comando. Deve ser sempre zero para gerações.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | SUM, MAX, MIN, AVG     |
| accepted          | Indica se o comando foi aceito.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | SUM, COUNT             |

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

<div id="valid-selections">
  #### Seleções válidas
</div>

| **Nome do campo**                | **Descrição**                                                                                                                                                                                                                                                                                         | **Agregações válidas** |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| percent\_code\_written           | Percentual de código escrito. Calculado como (número de bytes do codeium gerados) / (número de bytes do codeium gerados + número de bytes gerados pelo usuário). Essa métrica pode ter alta variabilidade em dias específicos ou entre usuários, por isso recomendamos agregá-la ao longo de semanas. | UNSPECIFIED            |
| codeium\_bytes                   | número total de bytes do codeium, que é igual a codeium\_bytes\_by\_autocomplete + codeium\_bytes\_by\_command                                                                                                                                                                                        | UNSPECIFIED            |
| user\_bytes                      | número total de bytes gerados pelo usuário                                                                                                                                                                                                                                                            | UNSPECIFIED            |
| total\_bytes                     | codeium\_bytes + user\_bytes                                                                                                                                                                                                                                                                          | UNSPECIFIED            |
| codeium\_bytes\_by\_autocomplete | número total de bytes do codeium gerados por autocompletar                                                                                                                                                                                                                                            | UNSPECIFIED            |
| codeium\_bytes\_by\_command      | número total de bytes do codeium gerados por comando                                                                                                                                                                                                                                                  | UNSPECIFIED            |

<div id="cascade-data">
  ### Dados do Cascade
</div>

A fonte de dados do Cascade contém uma entrada para cada mensagem enviada ao Cascade.

<Note>Para acessar todos os campos listados abaixo, verifique se você está usando a versão 1.11.2 ou posterior.</Note>

| **Nome do campo**   | **Descrição**                                                                                                                                                                                                            | **Agregações válidas**          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
| api\_key            | Um hash da chave de API do usuário.                                                                                                                                                                                      | UNSPECIFIED, COUNT              |
| date                | A data em UTC do comando.                                                                                                                                                                                                | UNSPECIFIED, COUNT              |
| prompts\_used       | O número de créditos de prompt usados no prompt enviado ao Cascade, retornado em centavos. Por exemplo, 0.25 crédito é retornado como 25, e 1 crédito é retornado como 100.                                              | UNSPECIFIED, SUM, AVG, MIN, MAX |
| flex\_credits\_used | O número de créditos adicionais/compartilhados usados do total de prompts\_used em um prompt enviado ao Cascade, retornado em centavos. Por exemplo, 0.25 crédito é retornado como 25, e 1 crédito é retornado como 100. | UNSPECIFIED, SUM, AVG, MIN, MAX |
| model               | O modelo usado na mensagem enviada ao Cascade.                                                                                                                                                                           | UNSPECIFIED, COUNT              |
| metadata            | Um objeto que contém metadados relacionados ao ambiente de desenvolvimento. Os campos preenchidos atualmente incluem: ideVersion                                                                                         | UNSPECIFIED, COUNT              |

<div id="valid-filters">
  #### Filtros válidos
</div>

|                   |                                                                    |                     |
| ----------------- | ------------------------------------------------------------------ | ------------------- |
| **Nome do campo** | **Descrição**                                                      | **Alguns exemplos** |
| api\_key          | Um hash da chave de API do usuário.                                |                     |
| language          | A linguagem de programação em uso.                                 | KOTLIN, GO, JAVA    |
| ide               | A 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, use start\_timestamp e end\_timestamp, que devem estar no formato RFC 3339 (por exemplo, 2023-01-01T00:00:00Z; consulte o exemplo abaixo).

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

<div id="user-data">
  ### Dados do usuário
</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
```

Esta consulta calcula o percentual geral de código escrito ao longo do mês de janeiro de 2024. Exemplo de resposta (JSON formatado para facilitar a leitura):

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

<div id="chat-data">
  ### Dados do 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
```

Esta consulta mostra o número de linhas de código aceitas a partir da lente de código "Generate Docstring" ao longo de todo o período, agrupadas por IDE.

Resposta de exemplo:

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

### Dados do comando

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

Esta consulta retorna o número de linhas adicionadas e removidas em comandos "edit", agrupado por linguagem de programação.

Resposta de exemplo:

```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">
  ### Dados do 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
```

Esta consulta retorna os dados de PCW (percentual de código escrito), além dos bytes filtrados para a linguagem Go.

Resposta de exemplo:

```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">
  ## Depuração de consultas
</div>

A partir da versão 1.10.0, consultas inválidas retornam uma mensagem de erro. Esta seção apresenta algumas mensagens de erro comuns, o que elas significam e como depurar as consultas correspondentes.

<table>
  <thead>
    <tr>
      <th>Mensagem de erro</th>
      <th>Explicação</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>at least one field or aggregation is required</td>
      <td>Nenhuma seleção ou agregação foi detectada — verifique se a requisição de consulta contém pelo menos uma.</td>
    </tr>

    <tr>
      <td>invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM</td>
      <td>Uma das seleções usou uma função de agregação inválida. Neste caso, tentamos usar SUM no campo "ide", mas ele só oferece suporte a COUNT e UNSPECIFIED.</td>
    </tr>

    <tr>
      <td>invalid query table: QUERY\_DATA\_SOURCE\_UNSPECIFIED</td>
      <td>Provavelmente há um erro de digitação no campo data\_source; verifique a grafia.</td>
    </tr>

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

      <td>
        Se houver vários campos de seleção, todos deverão conter um aggregation\_function, ou nenhum deles deverá conter. Por exemplo, esta seleção é inválida porque num\_acceptances está sendo somado, mas num\_lines\_accepted não está:

        ```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 considerado agregado. Se nenhum aggregation\_function for escolhido explicitamente, ele será considerado unspecified. Se você quiser informações sobre esses dois campos, use duas consultas separadas.
      </td>
    </tr>

    <tr>
      <td>invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM</td>
      <td>Nem todo campo oferece suporte a todas as funções de agregação; consulte a seção de campos disponíveis para ver quais combinações são válidas. Neste caso, a consulta usou a função de agregação QUERY\_AGGREGATION\_SUM com o campo "ide", o que é inválido.</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>
        Campos com o padrão "distinct\_\*" não podem estar na seção aggregations; a mensagem de erro sugere campos alternativos para agregar no lugar. Então, em vez de:

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

        Tente:

        ```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>Todas as seleções e agregações devem ter nomes diferentes. Lembre-se de que, se o nome não for especificado, por padrão ele será definido como \<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME>.</td>
    </tr>

    <tr>
      <td>invalid group name: GroupName</td>
      <td>O grupo com o nome especificado não foi encontrado; verifique a grafia.</td>
    </tr>
  </tbody>
</table>