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

# Analytics API（Enterprise SaaS）

> API 経由で、オートコンプリート、チャット、Command、Cascade、PCW のメトリクスを含む Devin Desktop の分析データをクエリできます。カスタムフィルター、集計、グループ化に対応しています。

<div id="overview">
  ## 概要
</div>

Devin Desktop は、カスタム分析用の API をサポートしています。オートコンプリート、チャット、Command に関するデータをクエリできるほか、さまざまなフィルタ、グループ化、集計にも対応しています。

すべての使用例は curl で示していますが、他の言語の HTTP リクエストにも置き換えられます。

<Note>Analytics API は Enterprise プランで利用できます</Note>

<div id="user-data-analytics-api-specification">
  ## ユーザーデータ Analytics API の仕様
</div>

TeamsページのUsersテーブルのデータは、次のコマンドで取得できます。

```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**: サービスキーです。管理者ユーザーは、設定ページのサービスキーセクションから作成できます。サービスキーのロールには、"Teams Read-only" 権限が必要です。

**GROUP\_NAME**: 絞り込みに使用するグループ名です。このフィールドは任意です。

**START\_TIMESTAMP/END\_TIMESTAMP**: RFC 3339 形式のタイムスタンプです。例: 2023-01-01T00:00:00Z

<div id="example-output">
  #### **出力例**
</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">
  ## Cascade Analytics API 仕様
</div>

[アナリティクスページ](https://windsurf.com/team/analytics)で確認できるCascade固有のデータは、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**: サービスキーです。管理者ユーザーは [チーム設定](https://windsurf.com/team/settings) から新しいキーを作成できます

**GROUP\_NAME**: フィルタリング対象のグループ名です。このフィールドは任意です。`emails` が設定されている場合は設定できません。

**START\_TIMESTAMP/END\_TIMESTAMP**: RFC 3339 形式のタイムスタンプです。たとえば `2023-01-01T00:00:00Z` です

**EMAILS**: フィルタリング対象のメールアドレスのリストです。このフィールドは任意です。`group&#95;name` が設定されている場合は設定できません。

**IDE\_TYPES**: フィルタリング対象の IDE タイプのリストです。このフィールドは任意です。指定可能な値は以下で説明します。

**QUERY\_REQUESTS**: 実行するクエリリクエストのリストです。このフィールドは必須です。CASCADE\_DATA\_SOURCE の指定可能な値は以下で説明します。

<div id="example-query">
  #### クエリの例
</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">
  ### IDE の種類
</div>

cascade データは IDE の種類ごとに分類されています。クエリで `ide_types` フィールドを指定しない場合は、すべての IDE のデータが返されます。特定の 1 つの IDE のデータだけをクエリする場合は、次のいずれかのオプションを利用できます。

* Devin Desktop Editor の場合は `"editor"`
* JetBrains Plugin の場合は `"jetbrains"`
* Devin CLI の場合は `"cli"`

<Note>Devin CLI (`"cli"`) で絞り込む場合、データが返されるのは `cascade_runs` のみです。`cascade_lines` と `cascade_tool_usage` のデータソースは Devin CLI ではサポートされておらず、空の結果が返されます。</Note>

<div id="cascade-data-sources">
  ### Cascade のデータソース
</div>

CASCADE\_DATA\_SOURCE には、3 つの値を設定できます

<div id="source-cascade_lines">
  #### ソース: cascade\_lines
</div>

1日ごとの、提案および受け入れられた cascade\_lines のデータをクエリするには、cascade\_lines を利用します。

出力例:

```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**: 指定日に提案された行数。
**linesAccepted**: 指定日に採用された行数。

<div id="source-cascade_runs">
  #### ソース: cascade\_runs
</div>

モデルの使用量、クレジット消費量、モードのデータをクエリするには、cascade\_runs を利用します。

出力例:

```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**: 実行日。

**model**: メッセージに使用されたモデル。

**mode**: 実行モード。CONVERSATIONAL\_PLANNER\_MODE\_DEFAULT (書き込みモード) 、CONVERSATIONAL\_PLANNER\_MODE\_READ\_ONLY (読み取りモード) 、CONVERSATIONAL\_PLANNER\_MODE\_NO\_TOOL (レガシーモード) 、または UNKNOWN のいずれかです。

**messagesSent**: 送信されたメッセージ数。

**cascadeId**: 実行の ID。この ID を使うと、ユーザーがメッセージを何回送信したかではなく、開始された個別の会話数を把握できます。

**promptsUsed**: 使用されたクレジット数。この値はセント単位で返されます。たとえば、0.25 クレジットは 25、1 クレジットは 100 として返されます。

API から返されるデータは生の形式であるため、"UNKNOWN" の値が含まれることがあります。このデータソースを独自のメトリクスに利用する場合は、関心のある具体的なメトリクスごとに集計することをおすすめします (例: `promptsUsed` フィールドを合計してユーザーの使用量パターンを把握する、`messagesSent` を集計してユーザーの利用状況を把握する、など) 。これは、mode と prompt のデータが複数のエントリに分かれて記録される可能性があるためです。

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

ツール使用量に関するデータをクエリするには、cascade\_tool\_usage を利用します。なお、返されるのは指定された期間内のツール利用回数の集計値です。

出力例:

```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**: そのメッセージで使用されたツール。

**count**: ツールが使用された回数。

以下は、返される列挙値と、UI に表示される表示名の対応表です。

* CODE\_ACTION: 'コード編集'
* VIEW\_FILE: 'ファイルを閲覧'
* RUN\_COMMAND: 'コマンドを実行'
* FIND: '検索ツール'
* GREP\_SEARCH: 'Grep 検索'
* VIEW\_FILE\_OUTLINE: 'ファイルのアウトラインを閲覧'
* MQUERY: 'Riptide'
* LIST\_DIRECTORY: 'ディレクトリを一覧表示'
* MCP\_TOOL: 'MCP ツール'
* PROPOSE\_CODE: 'コードを提案'
* SEARCH\_WEB: 'Web を検索'
* MEMORY: 'メモリ'
* PROXY\_WEB\_SERVER: 'ブラウザプレビュー'
* DEPLOY\_WEB\_APP: 'Web アプリをデプロイ'

<div id="custom-analytics-api-specification">
  ## Custom Analytics API の仕様
</div>

一部のデータソースでは、Custom Analytics API を介してクエリを柔軟にカスタマイズできます。

**選択、フィルター、集計、並べ替えの完全なスキーマは、次のセクションに JSON 形式で記載されています。3 つのデータソースそれぞれのクエリ例と、クエリのデバッグに関するヒントは、ドキュメントの末尾に記載しています。**

```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**: オートコンプリート、チャット、Command、PCW、または Cascade のどのデータを参照するかに応じて、USER\_DATA、CHAT\_DATA、COMMAND\_DATA、PCW\_DATA、または CASCADE\_DATA のいずれかを選択します。

**SERVICE\_KEY**: サービスキーです。管理者ユーザーは [チーム設定](https://windsurf.com/team/settings) から新しいサービスキーを作成できます。サービスキーのロールには、"Analytics Read" 権限が必要です。

**GROUP\_NAME**: フィルタリング対象のグループ名です。このフィールドは任意です。

<div id="schemas">
  ## スキーマ
</div>

<div id="selections">
  ### 選択
</div>

選択は**必須**です。各選択項目は、クエリする値に対応します。

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

**FIELD\_NAME**: クエリするフィールドです。以下の「Available Fields」セクションを参照してください。

**NAME**: フィールドの別名です。指定しない場合は、\<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME> の小文字版 (例: `sum&#95;num&#95;acceptances`) になります。他のすべてのフィールド名および集計名と重複しないようにする必要があります。

**AGGREGATION\_FUNCTION**: UNSPECIFIED、COUNT、SUM、AVG、MAX、MIN のいずれかを指定する必要があります。"aggregation\_function" が指定されていない場合、デフォルトは UNSPECIFIED です。

<div id="filters">
  ### フィルター
</div>

フィルターは、特定の条件を満たす要素のみを含むようにデータを絞り込むために利用されます。省略可能です。

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

**NAME**: フィルタするフィールドの名前です。フィルタ対象の項目が Selection/Aggregation と同じ場合、これはそのフィールド/集計の名前と一致している必要があります。

**VALUE**: 比較対象の値です。

**FILTER**: EQUAL、NOT\_EQUAL、GREATER\_THAN、LESS\_THAN、GE (以上) 、LE (以下) のいずれかです。

<div id="aggregations">
  ### 集計
</div>

集計は、指定した条件に基づいてデータをグループ分けするために利用されます。省略可能です。

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

FIELD\_NAME: クエリする対象のフィールドです。「Available Fields」セクションを参照してください。

NAME: フィールドの別名です。他のすべてのフィールド名および集計名と重複しない必要があります。

<div id="available-fields">
  ## 使用可能なフィールド
</div>

<div id="user-data">
  ### ユーザーデータ
</div>

USER\_DATA ソースのすべてのデータは、ユーザーごと・時間ごとに集計されます。

注: PCW (コード記述率) は現在、専用のテーブルを持っており、user\_data テーブルには依存していません。

| **Field Name**             | **Description**                                                              | **Valid Aggregations** |
| -------------------------- | ---------------------------------------------------------------------------- | ---------------------- |
| api\_key                   | ユーザーのAPIキーの hash。                                                            | UNSPECIFIED, COUNT     |
| date                       | オートコンプリートの UTC 日付。                                                           | UNSPECIFIED, COUNT     |
| date UTC-x                 | タイムゾーン オフセットを加味したオートコンプリートの日付。たとえば、PST の場合は "date UTC-8" になります。              | UNSPECIFIED, COUNT     |
| hour                       | オートコンプリートの UTC 時間。                                                           | UNSPECIFIED, COUNT     |
| language                   | 使用されているプログラミング言語。                                                            | UNSPECIFIED, COUNT     |
| ide                        | 使用されていた IDE。                                                                 | UNSPECIFIED, COUNT     |
| version                    | 拡張機能/プラグイン (language-server) のバージョン。例: `1.48.x`                              | UNSPECIFIED, COUNT     |
| num\_acceptances           | ユーザーがオートコンプリートを採用した回数。これは、ユーザーがコードをある程度記述し、グレーのテキストを確認して、tab キーを押したときに発生します。 | SUM, MAX, MIN, AVG     |
| num\_lines\_accepted       | オートコンプリートから採用したコード行数。                                                        | SUM, MAX, MIN, AVG     |
| num\_bytes\_accepted       | オートコンプリートから採用したバイト数。                                                         | SUM, MAX, MIN, AVG     |
| distinct\_users            | 重複を除いたユーザー数。                                                                 | UNSPECIFIED, COUNT     |
| distinct\_developer\_days  | 重複を除いた (users, day) の組み合わせ。                                                  | UNSPECIFIED, COUNT     |
| distinct\_developer\_hours | 重複を除いた (users, hour of day) の組み合わせ。                                          | UNSPECIFIED, COUNT     |

<div id="chat-data">
  ### チャットデータ
</div>

チャットデータ API で提供されるすべてのデータは、ユーザーの質問ではなく、チャットモデルの応答に関するものであることに注意してください。

| **Field Name**             | **Description**                                                                                                                                                                                                                                                                                                                                                                                                      | **Valid Aggregations** |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| api\_key                   | ユーザーのAPIキーのhash                                                                                                                                                                                                                                                                                                                                                                                                      | UNSPECIFIED, COUNT     |
| model\_id                  | デプロイ時に設定されるチャットモデルのID。                                                                                                                                                                                                                                                                                                                                                                                               | UNSPECIFIED, COUNT     |
| date                       | チャット応答の UTC 日付。                                                                                                                                                                                                                                                                                                                                                                                                      | UNSPECIFIED, COUNT     |
| date UTC-x                 | タイムゾーン オフセットを含むチャット応答の日付。たとえば、PST の場合は "date UTC-8" です。                                                                                                                                                                                                                                                                                                                                                              | UNSPECIFIED, COUNT     |
| ide                        | 使用されていた IDE                                                                                                                                                                                                                                                                                                                                                                                                          | UNSPECIFIED, COUNT     |
| version                    | 拡張機能/プラグイン (language-server) のバージョン。例: `1.48.x`                                                                                                                                                                                                                                                                                                                                                                      | UNSPECIFIED, COUNT     |
| latest\_intent\_type       | モデルの応答がコードレンズによって生成されたものか、通常のチャットによるものかを示します。通常のチャットは次に対応します:<br /><br />CHAT\_INTENT\_GENERIC<br /><br />コードレンズは次のいずれかに対応します:<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       | Devin Desktop からユーザーに送信されたチャットメッセージ数。                                                                                                                                                                                                                                                                                                                                                                                | SUM, MAX, MIN, AVG     |
| chat\_accepted             | Devin Desktop のチャット応答にコードブロックが含まれ、Thumbs up ボタンがクリックされた場合は True。                                                                                                                                                                                                                                                                                                                                                     | SUM, COUNT             |
| chat\_inserted\_at\_cursor | Devin Desktop のチャット応答にコードブロックが含まれ、"Insert" ボタンがクリックされた場合は True。                                                                                                                                                                                                                                                                                                                                                      | SUM, COUNT             |
| chat\_applied              | Devin Desktop のチャット応答にコードブロックが含まれ、"Apply Diff" ボタンがクリックされた場合は True。                                                                                                                                                                                                                                                                                                                                                  | SUM, COUNT             |
| chat\_loc\_used            | Devin Desktop のチャット応答にコードブロックが含まれ、"Insert"、"Copy"、または "Apply Diff" ボタンのいずれかが押された場合の利用コード行数。                                                                                                                                                                                                                                                                                                                          | SUM, MAX, MIN, AVG     |

<div id="command-data">
  ### Command データ
</div>

Command データソースには、拒否されたものも含めて**すべての**コマンドが含まれます。"採用" フィールドを利用すると、採用されたコマンドのみに絞り込めます。

| **Field Name**   | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | **Valid Aggregations** |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| api\_key         | ユーザーの APIキーの hash 値。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | UNSPECIFIED, COUNT     |
| date             | コマンドの UTC 日付。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | UNSPECIFIED, COUNT     |
| timestamp        | コマンドの UTC タイムスタンプ。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | UNSPECIFIED, COUNT     |
| language         | 利用されているプログラミング言語。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | UNSPECIFIED, COUNT     |
| ide              | 利用されていた IDE。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | UNSPECIFIED, COUNT     |
| version          | 拡張機能/プラグイン (language-server) のバージョン。例: `1.48.x`                                                                                                                                                                                                                                                                                                                                                                                                                                                           | UNSPECIFIED, COUNT     |
| command\_source  | コマンドがトリガーされた理由です。有効な値は次のとおりです。<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 は、通常の Command の利用に対応します。 | UNSPECIFIED, COUNT     |
| provider\_source | コマンドが生成モードと編集モードのどちらでトリガーされたかを示します。有効な値は次のとおりです。PROVIDER\_SOURCE\_COMMAND\_GENERATE PROVIDER\_SOURCE\_COMMAND\_EDIT                                                                                                                                                                                                                                                                                                                                                                                       | UNSPECIFIED, COUNT     |
| lines\_added     | コマンドによって追加されたコード行数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | SUM, MAX, MIN, AVG     |
| lines\_removed   | コマンドによって削除されたコード行数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | SUM, MAX, MIN, AVG     |
| bytes\_added     | コマンドによって追加されたバイト数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | SUM, MAX, MIN, AVG     |
| bytes\_removed   | コマンドによって削除されたバイト数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | SUM, MAX, MIN, AVG     |
| selection\_lines | コマンドによって選択されたコード行数。生成時は常にゼロになります。                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | SUM, MAX, MIN, AVG     |
| selection\_bytes | コマンドによって選択されたバイト数。生成時は常にゼロになります。                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | SUM, MAX, MIN, AVG     |
| accepted         | コマンドが採用されたかどうか。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | SUM, COUNT             |

### PCWデータ

<div id="valid-selections">
  #### 有効な選択項目
</div>

| **Field Name**                   | **Description**                                                                                                                       | **Valid Aggregations** |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| percent\_code\_written           | 記述されたコードの割合。(生成された codeium バイト数) / (生成された codeium バイト数 + ユーザーが記述したバイト数) として計算されます。この指標は、日単位やユーザー単位では変動が大きくなることがあるため、週単位で集計することを推奨します。 | UNSPECIFIED            |
| codeium\_bytes                   | codeium バイトの合計数。codeium\_bytes\_by\_autocomplete + codeium\_bytes\_by\_command と等しくなります                                               | UNSPECIFIED            |
| user\_bytes                      | ユーザーが記述したバイト数の合計                                                                                                                      | UNSPECIFIED            |
| total\_bytes                     | codeium\_bytes + user\_bytes                                                                                                          | UNSPECIFIED            |
| codeium\_bytes\_by\_autocomplete | オートコンプリートによって生成された codeium バイトの合計数                                                                                                    | UNSPECIFIED            |
| codeium\_bytes\_by\_command      | Command によって生成された codeium バイトの合計数                                                                                                     | UNSPECIFIED            |

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

Cascade Dataソースには、Cascade に送信される各メッセージごとにエントリが含まれます。

<Note>以下に記載されているすべてのフィールドにアクセスするには、バージョン 1.11.2 以降を使用していることを確認してください。</Note>

| **Field Name**      | **Description**                                                                                                      | **Valid Aggregations**          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| api\_key            | ユーザーのAPIキーのhash。                                                                                                     | UNSPECIFIED, COUNT              |
| date                | コマンドのUTC日付。                                                                                                          | UNSPECIFIED, COUNT              |
| prompts\_used       | Cascade へのプロンプトで使用されたprompt credits数で、セント単位で返されます。たとえば、0.25 クレジットは 25、1 クレジットは 100 として返されます。                         | UNSPECIFIED, SUM, AVG, MIN, MAX |
| flex\_credits\_used | Cascade へのプロンプトにおける prompts\_used 全体のうち、追加またはプールされたクレジットの使用数で、セント単位で返されます。たとえば、0.25 クレジットは 25、1 クレジットは 100 として返されます。 | UNSPECIFIED, SUM, AVG, MIN, MAX |
| model               | Cascade に送信されたメッセージで使用されたモデル。                                                                                        | UNSPECIFIED, COUNT              |
| metadata            | 開発環境に関連するメタデータを含むオブジェクト。現在、値が設定されるフィールドには次のものがあります: ideVersion                                                       | UNSPECIFIED, COUNT              |

<div id="valid-filters">
  #### 有効なフィルター
</div>

|                |                                                   |                   |
| -------------- | ------------------------------------------------- | ----------------- |
| **Field Name** | **説明**                                            | **使用例**           |
| api\_key       | ユーザーのAPIキーのhash値。                                 |                   |
| language       | 使用しているプログラミング言語。                                  | KOTLIN, GO, JAVA  |
| ide            | 使用していたIDE。                                        | jetbrains, vscode |
| version        | 拡張機能/プラグイン (language-server) のバージョン (例: `1.48.x`) | 1.28.0, 130.0     |

日付でフィルタリングするには、start\_timestamp と end\_timestamp を使用します。これらは RFC 3339 形式で指定する必要があります (例: 2023-01-01T00:00:00Z。以下の例を参照してください) 。

<div id="examples">
  ## 使用例
</div>

<div id="user-data">
  ### ユーザーデータ
</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
```

このクエリは、2024年1月の Percent Code Written の月間全体値を算出します。レスポンス例 (読みやすくするために JSON を整形しています) :

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

<div id="chat-data">
  ### チャットデータ
</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
```

このクエリは、"Generate Docstring" コードレンズから承認されたコード行数の累計を、IDE ごとに集計して表示します。

レスポンス例:

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

<div id="command-data">
  ### Command データ
</div>

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

このクエリは、"edit" コマンドで追加・削除された行数を、プログラミング言語別に取得します。

レスポンス例:

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

このクエリは、PCW (Percent Code Written) データと、言語 `go` でフィルタしたバイト数を取得します。

レスポンス例:

```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">
  ## クエリのデバッグ
</div>

1.10.0 以降では、無効なクエリに対してエラーメッセージが返されます。このセクションでは、よくあるエラーメッセージ、その意味、および該当するクエリのデバッグ方法を説明します。

<table>
  <thead>
    <tr>
      <th>エラーメッセージ</th>
      <th>説明</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>at least one field or aggregation is required</td>
      <td>選択または集計が 1 つも検出されませんでした。クエリリクエストに少なくとも 1 つ含まれていることを確認してください。</td>
    </tr>

    <tr>
      <td>invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM</td>
      <td>選択項目の 1 つで無効な集計関数が利用されています。この場合、"ide" フィールドに SUM を利用しようとしていますが、このフィールドがサポートしているのは COUNT と UNSPECIFIED のみです。</td>
    </tr>

    <tr>
      <td>invalid query table: QUERY\_DATA\_SOURCE\_UNSPECIFIED</td>
      <td>data\_source フィールドにスペルミスがある可能性があります。スペルを再確認してください。</td>
    </tr>

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

      <td>
        複数の選択フィールドがある場合は、すべてに aggregation\_function を含めるか、どれにも含めないようにする必要があります。たとえば、次の選択は無効です。num\_acceptances には合計が指定されていますが、num\_lines\_accepted には指定されていないためです。

        ```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"
          }
        ]
        ```

        注: PCW は常に集計済みとして扱われます。aggregation\_function が明示的に選択されていない場合は、unspecified と見なされます。これら両方のフィールドの情報が必要な場合は、別々の 2 つのクエリを利用してください。
      </td>
    </tr>

    <tr>
      <td>invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM</td>
      <td>すべてのフィールドがすべての集計関数をサポートしているわけではありません。対応関係については、利用可能なフィールドのセクションを参照してください。この場合、クエリでは "ide" フィールドに QUERY\_AGGREGATION\_SUM 集計関数を利用していますが、これは無効です。</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>
        "distinct\_\*" パターンのフィールドは aggregations セクションに含めることはできません。このエラーでは、代わりに集計対象として利用できるフィールドが提案されています。したがって、次の代わりに:

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

        次を試してください:

        ```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>すべての selections と aggregations には異なる name が必要です。name が指定されていない場合、デフォルトでは \<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME> に設定されることに注意してください。</td>
    </tr>

    <tr>
      <td>invalid group name: GroupName</td>
      <td>指定された名前のグループが見つかりませんでした。スペルを再確認してください。</td>
    </tr>
  </tbody>
</table>
