> ## 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 analíticas

> Consultas flexibles de analíticas con selecciones, filtros y agregaciones personalizadas para datos de autocompletado, chat, Command y PCW.

<div id="overview">
  ## Descripción general
</div>

La API de analíticas personalizadas permite hacer consultas flexibles sobre datos de autocompletado, chat y Command, con selecciones, filtros, agregaciones y criterios de ordenación personalizables.

<div id="request">
  ## Solicitud
</div>

<ParamField body="service_key" type="string" required>
  Tu clave de servicio con permisos de "Analytics Read"
</ParamField>

<ParamField body="group_name" type="string">
  Filtra los resultados para mostrar solo los usuarios de un grupo específico (opcional)
</ParamField>

<ParamField body="query_requests" type="array" required>
  Array de objetos de solicitud de consulta que definen los datos que se van a recuperar

  <Expandable title="Objeto de solicitud de consulta">
    <ParamField body="data_source" type="string" required>
      Origen de datos que se va a consultar. Opciones:

      * `QUERY_DATA_SOURCE_USER_DATA` - Datos de autocompletado
      * `QUERY_DATA_SOURCE_CHAT_DATA` - Datos de chat
      * `QUERY_DATA_SOURCE_COMMAND_DATA` - Datos de Command
      * `QUERY_DATA_SOURCE_PCW_DATA` - Datos de porcentaje de código escrito
    </ParamField>

    <ParamField body="selections" type="array" required>
      Array de selecciones de campos que se van a recuperar

      <Expandable title="Objeto de selección">
        <ParamField body="field" type="string" required>
          Nombre del campo que se va a seleccionar (consulta la sección Campos disponibles)
        </ParamField>

        <ParamField body="name" type="string">
          Alias del campo. Si no se especifica, el valor predeterminado es `{aggregation_function}_{field_name}` (en minúsculas)
        </ParamField>

        <ParamField body="aggregation_function" type="string">
          Función de agregación que se va a aplicar:

          * `QUERY_AGGREGATION_UNSPECIFIED` (predeterminado)
          * `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 que se van a aplicar

      <Expandable title="Objeto de filtro">
        <ParamField body="name" type="string" required>
          Nombre del campo por el que se va a filtrar
        </ParamField>

        <ParamField body="filter" type="string" required>
          Operación de filtro:

          * `QUERY_FILTER_EQUAL`
          * `QUERY_FILTER_NOT_EQUAL`
          * `QUERY_FILTER_GREATER_THAN`
          * `QUERY_FILTER_LESS_THAN`
          * `QUERY_FILTER_GE` (mayor o igual que)
          * `QUERY_FILTER_LE` (menor o igual que)
        </ParamField>

        <ParamField body="value" type="string" required>
          Valor con el que se va a comparar
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="aggregations" type="array">
      Array de agregaciones para agrupar

      <Expandable title="Objeto de agregación">
        <ParamField body="field" type="string" required>
          Nombre del campo por el que se va a agrupar
        </ParamField>

        <ParamField body="name" type="string" required>
          Alias del campo de agregación
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<div id="query-request-structure">
  ## Estructura de la solicitud de consulta
</div>

Cada objeto de solicitud de consulta contiene:

* **data\_source** (obligatorio): fuente de datos que se va a consultar
* **selections** (obligatorio): array de selecciones de campos que se van a recuperar
* **filters** (opcional): array de filtros que se van a aplicar
* **aggregations** (opcional): array de agregaciones para agrupar por

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

Las selecciones definen qué campos obtener y cómo agregarlos.

* **field** (obligatorio): Nombre del campo que se va a seleccionar
* **name** (opcional): Alias del campo
* **aggregation\_function** (opcional): Función de agregación que se va a aplicar

<div id="selection-example">
  ### Ejemplo de selección
</div>

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

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

Los filtros permiten limitar los datos a los elementos que cumplen criterios específicos.

* **name** (obligatorio): Nombre del campo por el que filtrar
* **filter** (obligatorio): Operación de filtro
* **value** (obligatorio): Valor con el que comparar

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

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

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

Las agregaciones agrupan los datos según los criterios especificados.

* **field** (obligatorio): Nombre del campo por el que se agrupan los datos
* **name** (obligatorio): Alias del campo de agregación

<div id="aggregation-example">
  ### Ejemplo de agregación
</div>

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

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

<div id="user-data">
  ### Datos del usuario
</div>

Todos los datos del usuario se agregan por usuario y por hora.

| Nombre del campo           | Descripción                                                              | Agregaciones válidas |
| -------------------------- | ------------------------------------------------------------------------ | -------------------- |
| `api_key`                  | Hash de la clave de API del usuario                                      | UNSPECIFIED, COUNT   |
| `date`                     | Fecha UTC del autocompletado                                             | UNSPECIFIED, COUNT   |
| `date UTC-x`               | Fecha con desplazamiento de zona horaria (p. ej., "date UTC-8" para PST) | UNSPECIFIED, COUNT   |
| `hour`                     | Hora UTC del autocompletado                                              | UNSPECIFIED, COUNT   |
| `language`                 | Lenguaje de programación                                                 | UNSPECIFIED, COUNT   |
| `ide`                      | IDE en uso                                                               | UNSPECIFIED, COUNT   |
| `version`                  | Versión de la extensión/plugin (language-server), p. ej. `1.48.x`        | UNSPECIFIED, COUNT   |
| `num_acceptances`          | Número de aceptaciones de autocompletado                                 | SUM, MAX, MIN, AVG   |
| `num_lines_accepted`       | Líneas de código aceptadas                                               | SUM, MAX, MIN, AVG   |
| `num_bytes_accepted`       | Bytes aceptados                                                          | SUM, MAX, MIN, AVG   |
| `distinct_users`           | Usuarios distintos                                                       | UNSPECIFIED, COUNT   |
| `distinct_developer_days`  | Tuplas distintas de (usuario, día)                                       | UNSPECIFIED, COUNT   |
| `distinct_developer_hours` | Tuplas distintas de (usuario, hora)                                      | UNSPECIFIED, COUNT   |

<div id="chat-data">
  ### Datos del chat
</div>

<Info>Los datos del chat están separados de los datos de Cascade y representan el uso de nuestros plugins heredados no basados en agentes</Info>

Todos los datos del chat representan respuestas del modelo de chat, no preguntas del usuario.

| Nombre del campo          | Descripción                                                                 | Agregaciones válidas |
| ------------------------- | --------------------------------------------------------------------------- | -------------------- |
| `api_key`                 | Hash de la clave de API del usuario                                         | UNSPECIFIED, COUNT   |
| `model_id`                | ID del modelo de chat                                                       | UNSPECIFIED, COUNT   |
| `date`                    | Fecha UTC de la respuesta del chat                                          | UNSPECIFIED, COUNT   |
| `date UTC-x`              | Fecha con desfase de zona horaria                                           | UNSPECIFIED, COUNT   |
| `ide`                     | IDE en uso                                                                  | UNSPECIFIED, COUNT   |
| `version`                 | Versión de la extensión/plugin (language-server), p. ej. `1.48.x`           | UNSPECIFIED, COUNT   |
| `latest_intent_type`      | Tipo de intención del chat (consulta los tipos de intención a continuación) | UNSPECIFIED, COUNT   |
| `num_chats_received`      | Número de mensajes de chat recibidos                                        | SUM, MAX, MIN, AVG   |
| `chat_accepted`           | Si el chat fue aceptado (pulgar arriba)                                     | SUM, COUNT           |
| `chat_inserted_at_cursor` | Si se hizo clic en el botón "Insert"                                        | SUM, COUNT           |
| `chat_applied`            | Si se hizo clic en el botón "Apply Diff"                                    | SUM, COUNT           |
| `chat_loc_used`           | Líneas de código utilizadas del chat                                        | SUM, MAX, MIN, AVG   |

<div id="chat-intent-types">
  #### Tipos de intención del chat
</div>

* `CHAT_INTENT_GENERIC` - Chat normal
* `CHAT_INTENT_FUNCTION_EXPLAIN` - code lens de explicación de la función
* `CHAT_INTENT_FUNCTION_DOCSTRING` - code lens del docstring de la función
* `CHAT_INTENT_FUNCTION_REFACTOR` - code lens de refactorización de la función
* `CHAT_INTENT_CODE_BLOCK_EXPLAIN` - code lens de explicación del bloque de código
* `CHAT_INTENT_CODE_BLOCK_REFACTOR` - code lens de refactorización del bloque de código
* `CHAT_INTENT_PROBLEM_EXPLAIN` - code lens de explicación del problema
* `CHAT_INTENT_FUNCTION_UNIT_TESTS` - code lens de pruebas unitarias de la función

<div id="command-data">
  ### Datos de Command
</div>

Los datos de Command incluyen todos los comandos, incluidos los rechazados. Usa el campo `accepted` para filtrar únicamente los comandos aceptados.

| Nombre del campo  | Descripción                                                             | Agregaciones válidas |
| ----------------- | ----------------------------------------------------------------------- | -------------------- |
| `api_key`         | Hash de la clave de API del usuario                                     | UNSPECIFIED, COUNT   |
| `date`            | Fecha UTC del comando                                                   | UNSPECIFIED, COUNT   |
| `timestamp`       | Marca de tiempo UTC del comando                                         | UNSPECIFIED, COUNT   |
| `language`        | Lenguaje de programación                                                | UNSPECIFIED, COUNT   |
| `ide`             | IDE en uso                                                              | UNSPECIFIED, COUNT   |
| `version`         | Versión de la extensión/plugin (language-server), p. ej. `1.48.x`       | UNSPECIFIED, COUNT   |
| `command_source`  | Origen de activación de Command (consulta Fuentes de Command más abajo) | UNSPECIFIED, COUNT   |
| `provider_source` | Modo de generación o edición                                            | UNSPECIFIED, COUNT   |
| `lines_added`     | Líneas de código agregadas                                              | SUM, MAX, MIN, AVG   |
| `lines_removed`   | Líneas de código eliminadas                                             | SUM, MAX, MIN, AVG   |
| `bytes_added`     | Bytes agregados                                                         | SUM, MAX, MIN, AVG   |
| `bytes_removed`   | Bytes eliminados                                                        | SUM, MAX, MIN, AVG   |
| `selection_lines` | Líneas seleccionadas (cero para generaciones)                           | SUM, MAX, MIN, AVG   |
| `selection_bytes` | Bytes seleccionados (cero para generaciones)                            | SUM, MAX, MIN, AVG   |
| `accepted`        | Indica si el comando fue aceptado                                       | SUM, COUNT           |

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

* `COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_DEFAULT` - Uso típico 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">
  #### Fuentes del proveedor
</div>

* `PROVIDER_SOURCE_COMMAND_GENERATE` - Modo de generación
* `PROVIDER_SOURCE_COMMAND_EDIT` - Modo de edición

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

Datos del porcentaje de código escrito, con seguimiento independiente de las contribuciones de autocompletado y de Command.

| Nombre del campo                | Descripción                                                     | Agregaciones válidas |
| ------------------------------- | --------------------------------------------------------------- | -------------------- |
| `percent_code_written`          | Se calcula como codeium\_bytes / (codeium\_bytes + user\_bytes) | UNSPECIFIED          |
| `codeium_bytes`                 | Total de bytes generados por Codeium                            | UNSPECIFIED          |
| `user_bytes`                    | Total de bytes escritos por el usuario                          | UNSPECIFIED          |
| `total_bytes`                   | codeium\_bytes + user\_bytes                                    | UNSPECIFIED          |
| `codeium_bytes_by_autocomplete` | Bytes de Codeium procedentes del autocompletado                 | UNSPECIFIED          |
| `codeium_bytes_by_command`      | Bytes de Codeium procedentes de Command                         | UNSPECIFIED          |

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

| Nombre del campo | Descripción                                                       | Ejemplos          |
| ---------------- | ----------------------------------------------------------------- | ----------------- |
| `language`       | Lenguaje de programación                                          | KOTLIN, GO, JAVA  |
| `ide`            | IDE utilizado                                                     | jetbrains, vscode |
| `version`        | Versión de la extensión/plugin (language-server), p. ej. `1.48.x` | 1.28.0, 130.0     |

Para filtrar por fecha en las consultas de PCW, usa `start_timestamp` y `end_timestamp` en el cuerpo principal de la solicitud.

<div id="example-requests">
  ## Ejemplos de peticiones
</div>

<div id="user-data-example">
  ### Ejemplo de datos de usuario
</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">
  ### Ejemplo de datos del 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">
  ### Ejemplo de datos para 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">
  ### Ejemplo de datos 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">
  ## Respuesta
</div>

<ResponseField name="queryResults" type="array">
  Array de resultados de consulta, uno por cada solicitud de consulta

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

    <ResponseField name="item" type="object">
      Objeto que contiene los campos seleccionados y sus valores
    </ResponseField>
  </ResponseField>
</ResponseField>

<div id="example-responses">
  ### Ejemplos de respuesta
</div>

<div id="user-data-response">
  #### Respuesta de datos del usuario
</div>

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

<div id="chat-data-response">
  #### Respuesta de datos del 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">
  #### Respuesta de datos 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">
  #### Respuesta de datos 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>

* PCW (Percent Code Written) presenta una alta variabilidad en un mismo día o entre usuarios; agrupa los datos por semanas para obtener mejores resultados
* Todos los campos de selección deben tener funciones de agregación, o ninguno debe tenerlas (no se pueden mezclar)
* Los campos con el patrón "distinct\_\*" no se pueden usar en agregaciones
* Los alias de los campos deben ser únicos en todas las selecciones y agregaciones
* Si no se especifica ninguna función de agregación, el valor predeterminado es UNSPECIFIED