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

# Benutzerdefinierte Analytics-Abfrage

> Flexible Analytics-Abfragen mit benutzerdefinierten Auswahlen, Filtern und Aggregationen für Autovervollständigungs-, Chat-, Befehls- und PCW-Daten.

<div id="overview">
  ## Überblick
</div>

Die Custom Analytics API ermöglicht flexible Abfragen von Autovervollständigungs-, Chat- und Befehlsdaten mit anpassbarer Auswahl, Filtern, Aggregationen und Sortierungen.

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

<ParamField body="service_key" type="string" required>
  Ihr Service-Schlüssel mit „Analytics Read“-Berechtigungen
</ParamField>

<ParamField body="group_name" type="string">
  Ergebnisse auf Nutzer in einer bestimmten Gruppe beschränken (optional)
</ParamField>

<ParamField body="query_requests" type="array" required>
  Array von Abfrageobjekten, die die abzurufenden Daten definieren

  <Expandable title="Abfrageobjekt">
    <ParamField body="data_source" type="string" required>
      Abzufragende Datenquelle. Optionen:

      * `QUERY_DATA_SOURCE_USER_DATA` - Daten zur Autovervollständigung
      * `QUERY_DATA_SOURCE_CHAT_DATA` - Chat-Daten
      * `QUERY_DATA_SOURCE_COMMAND_DATA` - Befehlsdaten
      * `QUERY_DATA_SOURCE_PCW_DATA` - Daten zum Prozentsatz des geschriebenen Codes
    </ParamField>

    <ParamField body="selections" type="array" required>
      Array von Feldauswahlen zum Abrufen

      <Expandable title="Auswahlobjekt">
        <ParamField body="field" type="string" required>
          Name des auszuwählenden Felds (siehe Abschnitt „Available Fields“)
        </ParamField>

        <ParamField body="name" type="string">
          Alias für das Feld. Falls nicht angegeben, wird standardmäßig `{aggregation_function}_{field_name}` verwendet (in Kleinbuchstaben)
        </ParamField>

        <ParamField body="aggregation_function" type="string">
          Anzuwendende Aggregationsfunktion:

          * `QUERY_AGGREGATION_UNSPECIFIED` (Standard)
          * `QUERY_AGGREGATION_COUNT`
          * `QUERY_AGGREGATION_SUM`
          * `QUERY_AGGREGATION_AVG`
          * `QUERY_AGGREGATION_MAX`
          * `QUERY_AGGREGATION_MIN`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="filters" type="array">
      Array von anzuwendenden Filtern

      <Expandable title="Filterobjekt">
        <ParamField body="name" type="string" required>
          Name des Felds, nach dem gefiltert werden soll
        </ParamField>

        <ParamField body="filter" type="string" required>
          Filteroperation:

          * `QUERY_FILTER_EQUAL`
          * `QUERY_FILTER_NOT_EQUAL`
          * `QUERY_FILTER_GREATER_THAN`
          * `QUERY_FILTER_LESS_THAN`
          * `QUERY_FILTER_GE` (größer oder gleich)
          * `QUERY_FILTER_LE` (kleiner oder gleich)
        </ParamField>

        <ParamField body="value" type="string" required>
          Vergleichswert
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="aggregations" type="array">
      Array von Aggregationen zum Gruppieren

      <Expandable title="Aggregationsobjekt">
        <ParamField body="field" type="string" required>
          Name des Felds, nach dem gruppiert werden soll
        </ParamField>

        <ParamField body="name" type="string" required>
          Alias für das Aggregationsfeld
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<div id="query-request-structure">
  ## Struktur der Query-Anfrage
</div>

Jedes Abfrageobjekt enthält:

* **data\_source** (erforderlich): Abzufragende Datenquelle
* **selections** (erforderlich): Array der abzurufenden Feldauswahlen
* **filters** (optional): Array der anzuwendenden Filter
* **aggregations** (optional): Array der Aggregationen zur Gruppierung

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

Auswahlen legen fest, welche Felder abgerufen und wie sie aggregiert werden.

* **field** (erforderlich): Name des Felds, das ausgewählt werden soll
* **name** (optional): Alias für das Feld
* **aggregation\_function** (optional): Anzuwendende Aggregationsfunktion

<div id="selection-example">
  ### Beispiel für eine Auswahl
</div>

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

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

Filter schränken Daten auf Elemente ein, die bestimmte Kriterien erfüllen.

* **name** (erforderlich): Feldname, nach dem gefiltert werden soll
* **filter** (erforderlich): Filteroperation
* **value** (erforderlich): Wert, mit dem verglichen werden soll

<div id="filter-example">
  ### Beispiel für einen Filter
</div>

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

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

Aggregationen fassen Daten nach angegebenen Kriterien zusammen.

* **field** (erforderlich): Feldname, nach dem gruppiert wird
* **name** (erforderlich): Alias für das Aggregationsfeld

<div id="aggregation-example">
  ### Beispiel für eine Aggregation
</div>

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

<div id="available-fields">
  ## Verfügbare Felder
</div>

<div id="user-data">
  ### Nutzerdaten
</div>

Alle Nutzerdaten werden pro Nutzer und Stunde aggregiert.

| Feldname                   | Beschreibung                                                          | Gültige Aggregationen |
| -------------------------- | --------------------------------------------------------------------- | --------------------- |
| `api_key`                  | Hash des API-Schlüssels des Nutzers                                   | UNSPECIFIED, COUNT    |
| `date`                     | UTC-Datum der Autovervollständigung                                   | UNSPECIFIED, COUNT    |
| `date UTC-x`               | Datum mit Zeitzonenversatz (z. B. „date UTC-8“ für PST)               | UNSPECIFIED, COUNT    |
| `hour`                     | UTC-Stunde der Autovervollständigung                                  | UNSPECIFIED, COUNT    |
| `language`                 | Programmiersprache                                                    | UNSPECIFIED, COUNT    |
| `ide`                      | Verwendete IDE                                                        | UNSPECIFIED, COUNT    |
| `version`                  | Version der Erweiterung/des Plugins (Language Server), z. B. `1.48.x` | UNSPECIFIED, COUNT    |
| `num_acceptances`          | Anzahl akzeptierter Autovervollständigungen                           | SUM, MAX, MIN, AVG    |
| `num_lines_accepted`       | Akzeptierte Codezeilen                                                | SUM, MAX, MIN, AVG    |
| `num_bytes_accepted`       | Akzeptierte Bytes                                                     | SUM, MAX, MIN, AVG    |
| `distinct_users`           | Eindeutige Nutzer                                                     | UNSPECIFIED, COUNT    |
| `distinct_developer_days`  | Eindeutige Tupel aus (Nutzer, Tag)                                    | UNSPECIFIED, COUNT    |
| `distinct_developer_hours` | Eindeutige Tupel aus (Nutzer, Stunde)                                 | UNSPECIFIED, COUNT    |

<div id="chat-data">
  ### Chat-Daten
</div>

<Info>Chat-Daten sind von Cascade-Daten getrennt und erfassen die Nutzung unserer älteren, nicht-agentischen Plugins</Info>

Alle Chat-Daten beziehen sich auf Antworten des Chatmodells, nicht auf Fragen von Nutzern.

| Feldname                  | Beschreibung                                                          | Gültige Aggregationen |
| ------------------------- | --------------------------------------------------------------------- | --------------------- |
| `api_key`                 | Hash des API-Schlüssels des Nutzers                                   | UNSPECIFIED, COUNT    |
| `model_id`                | ID des Chatmodells                                                    | UNSPECIFIED, COUNT    |
| `date`                    | UTC-Datum der Chat-Antwort                                            | UNSPECIFIED, COUNT    |
| `date UTC-x`              | Datum mit Zeitzonenversatz                                            | UNSPECIFIED, COUNT    |
| `ide`                     | Verwendete IDE                                                        | UNSPECIFIED, COUNT    |
| `version`                 | Version der Erweiterung/des Plugins (Language Server), z. B. `1.48.x` | UNSPECIFIED, COUNT    |
| `latest_intent_type`      | Chat-Intent-Typ (siehe Intent-Typen unten)                            | UNSPECIFIED, COUNT    |
| `num_chats_received`      | Anzahl der empfangenen Chat-Nachrichten                               | SUM, MAX, MIN, AVG    |
| `chat_accepted`           | Ob der Chat akzeptiert wurde („Daumen hoch“)                          | SUM, COUNT            |
| `chat_inserted_at_cursor` | Ob auf die Schaltfläche „Insert“ geklickt wurde                       | SUM, COUNT            |
| `chat_applied`            | Ob auf die Schaltfläche „Apply Diff“ geklickt wurde                   | SUM, COUNT            |
| `chat_loc_used`           | Aus dem Chat übernommene Codezeilen                                   | SUM, MAX, MIN, AVG    |

<div id="chat-intent-types">
  #### Chat-Intent-Typen
</div>

* `CHAT_INTENT_GENERIC` - Regulärer Chat
* `CHAT_INTENT_FUNCTION_EXPLAIN` - CodeLens zur Erklärung einer Funktion
* `CHAT_INTENT_FUNCTION_DOCSTRING` - CodeLens für den Docstring einer Funktion
* `CHAT_INTENT_FUNCTION_REFACTOR` - CodeLens zum Refactoring einer Funktion
* `CHAT_INTENT_CODE_BLOCK_EXPLAIN` - CodeLens zur Erklärung eines Codeblocks
* `CHAT_INTENT_CODE_BLOCK_REFACTOR` - CodeLens zum Refactoring eines Codeblocks
* `CHAT_INTENT_PROBLEM_EXPLAIN` - CodeLens zur Problemerklärung
* `CHAT_INTENT_FUNCTION_UNIT_TESTS` - CodeLens für Unit-Tests einer Funktion

<div id="command-data">
  ### Befehlsdaten
</div>

Befehlsdaten umfassen alle Befehle, einschließlich abgelehnter. Verwenden Sie das Feld `accepted`, um nur akzeptierte Befehle zu filtern.

| Feldname          | Beschreibung                                                              | Gültige Aggregationen |
| ----------------- | ------------------------------------------------------------------------- | --------------------- |
| `api_key`         | Hash des API-Schlüssels des Nutzers                                       | UNSPECIFIED, COUNT    |
| `date`            | UTC-Datum des Befehls                                                     | UNSPECIFIED, COUNT    |
| `timestamp`       | UTC-Zeitstempel des Befehls                                               | UNSPECIFIED, COUNT    |
| `language`        | Programmiersprache                                                        | UNSPECIFIED, COUNT    |
| `ide`             | Verwendete IDE                                                            | UNSPECIFIED, COUNT    |
| `version`         | Erweiterung/Plugin-Version (Language Server), z. B. `1.48.x`              | UNSPECIFIED, COUNT    |
| `command_source`  | Quelle, durch die der Befehl ausgelöst wurde (siehe Befehlsquellen unten) | UNSPECIFIED, COUNT    |
| `provider_source` | Generierungs- oder Bearbeitungsmodus                                      | UNSPECIFIED, COUNT    |
| `lines_added`     | Hinzugefügte Codezeilen                                                   | SUM, MAX, MIN, AVG    |
| `lines_removed`   | Entfernte Codezeilen                                                      | SUM, MAX, MIN, AVG    |
| `bytes_added`     | Hinzugefügte Bytes                                                        | SUM, MAX, MIN, AVG    |
| `bytes_removed`   | Entfernte Bytes                                                           | SUM, MAX, MIN, AVG    |
| `selection_lines` | Ausgewählte Zeilen (0 bei Generierungen)                                  | SUM, MAX, MIN, AVG    |
| `selection_bytes` | Ausgewählte Bytes (0 bei Generierungen)                                   | SUM, MAX, MIN, AVG    |
| `accepted`        | Gibt an, ob der Befehl akzeptiert wurde                                   | SUM, COUNT            |

<div id="command-sources">
  #### Befehlsquellen
</div>

* `COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS`
* `COMMAND_REQUEST_SOURCE_DEFAULT` - Typische Nutzung von Befehlen
* `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">
  #### Provider-Quellen
</div>

* `PROVIDER_SOURCE_COMMAND_GENERATE` - Generierungsmodus
* `PROVIDER_SOURCE_COMMAND_EDIT` - Bearbeitungsmodus

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

Daten zu „Percent Code Written“ mit separater Erfassung von Beiträgen durch Autovervollständigung und Befehle.

| Feldname                        | Beschreibung                                                  | Gültige Aggregationen |
| ------------------------------- | ------------------------------------------------------------- | --------------------- |
| `percent_code_written`          | Berechnet als codeium\_bytes / (codeium\_bytes + user\_bytes) | UNSPECIFIED           |
| `codeium_bytes`                 | Insgesamt von Codeium generierte Bytes                        | UNSPECIFIED           |
| `user_bytes`                    | Insgesamt vom Nutzer geschriebene Bytes                       | UNSPECIFIED           |
| `total_bytes`                   | codeium\_bytes + user\_bytes                                  | UNSPECIFIED           |
| `codeium_bytes_by_autocomplete` | Codeium-Bytes aus Autovervollständigung                       | UNSPECIFIED           |
| `codeium_bytes_by_command`      | Codeium-Bytes aus Befehlen                                    | UNSPECIFIED           |

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

| Feldname   | Beschreibung                                                          | Beispiele         |
| ---------- | --------------------------------------------------------------------- | ----------------- |
| `language` | Programmiersprache                                                    | KOTLIN, GO, JAVA  |
| `ide`      | Verwendete IDE                                                        | jetbrains, vscode |
| `version`  | Version der Erweiterung/des Plugins (Language Server), z. B. `1.48.x` | 1.28.0, 130.0     |

Verwenden Sie für die Datumsfilterung in PCW-Abfragen `start_timestamp` und `end_timestamp` im Hauptteil des Request-Bodys.

<div id="example-requests">
  ## Beispielanfragen
</div>

<div id="user-data-example">
  ### Beispiel für Nutzerdaten
</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">
  ### Beispiel für Chat-Daten
</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">
  ### Beispiel für Befehlsdaten
</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">
  ### Beispiel für PCW-Daten
</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">
  ## Antwort
</div>

<ResponseField name="queryResults" type="array">
  Array mit Abfrageergebnissen, eines für jede Abfrage

  <ResponseField name="responseItems" type="array">
    Array mit Ergebniseinträgen

    <ResponseField name="item" type="object">
      Objekt mit den ausgewählten Feldern und ihren Werten
    </ResponseField>
  </ResponseField>
</ResponseField>

<div id="example-responses">
  ### Beispielantworten
</div>

<div id="user-data-response">
  #### Antwort mit Nutzerdaten
</div>

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

<div id="chat-data-response">
  #### Antwort mit Chat-Daten
</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">
  #### Antwort mit Befehlsdaten
</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">
  #### Antwort mit PCW-Daten
</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">
  ## Wichtige Hinweise
</div>

* PCW (Percent Code Written) weist innerhalb einzelner Tage oder bei einzelnen Nutzern eine hohe Varianz auf – für aussagekräftigere Ergebnisse über mehrere Wochen aggregieren
* Alle Auswahlfelder müssen entweder Aggregationsfunktionen haben oder keines darf eine haben (eine Mischung ist nicht möglich)
* Felder mit dem Muster "distinct\_\*" können nicht in Aggregationen verwendet werden
* Feldaliase müssen über alle Auswahlen und Aggregationen hinweg eindeutig sein
* Wenn keine Aggregationsfunktion angegeben ist, wird standardmäßig UNSPECIFIED verwendet