> ## 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（Enterprise SaaS）

> 通过 API 查询 Devin Desktop 的分析数据，包括自动补全、聊天、命令、Cascade 和 PCW 指标。支持自定义筛选条件、聚合和分组。

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

Devin Desktop 提供用于自定义分析的 API。您可以查询自动补全、聊天和命令相关的数据，并使用多种筛选、分组和聚合方式。

我们所有示例均使用 curl；随后可将其转换为其他语言中的 HTTP 请求。

<Note>分析 API 适用于 Enterprise 套餐</Note>

<div id="user-data-analytics-api-specification">
  ## 用户数据分析 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**：服务密钥——Admin 用户可在设置页面的服务密钥部分创建该密钥。该服务密钥的 role 必须具有 "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 分析 API 规范
</div>

[analytics 页面](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**：服务密钥——Admin 用户可以在[团队设置](https://windsurf.com/team/settings)中创建新的密钥

**GROUP\_NAME**：要筛选的组名称。此字段为可选。如果设置了 emails，则不能设置此字段。

**START\_TIMESTAMP/END\_TIMESTAMP**：RFC 3339 格式的时间戳，例如 2023-01-01T00:00:00Z

**EMAILS**：要筛选的电子邮件列表。此字段为可选。如果设置了 group\_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>

我们按 IDE 类型对 cascade 数据进行分类。如果查询中不包含 ide\_types 字段，则会返回所有类型的数据。如果你只想查询某一种 IDE 的数据，可以使用以下任一选项：

* "editor" 表示 Devin Desktop Editor
* "jetbrains" 表示 JetBrains 插件
* "cli" 表示 Devin CLI

<Note>按 Devin CLI (`"cli"`) 筛选时，只有 `cascade_runs` 会返回数据。Devin CLI 不支持 `cascade_lines` 和 `cascade_tool_usage` 数据源，因此会返回空结果。</Note>

<div id="cascade-data-sources">
  ### Cascade 数据源
</div>

CASCADE\_DATA\_SOURCE 有以下三种可能的取值

<div id="source-cascade_lines">
  #### 来源：cascade\_lines
</div>

使用 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 查询模型用量、credit 消耗和模式相关数据。

示例输出：

```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**: 已使用的 credits 数量。该值以分为单位返回。例如，0.25 credits 会返回为 25，而 1 credit 会返回为 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: 'Browser 预览'
* DEPLOY\_WEB\_APP: '部署 Web 应用'

<div id="custom-analytics-api-specification">
  ## 自定义分析 API 规范
</div>

某些数据源支持通过自定义分析 API 执行自定义查询。

**选择、筛选、聚合和排序的完整结构定义位于下一节，并以 JSON 格式提供。三个数据源各自的示例查询以及查询调试提示将在文档末尾给出。**

```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**：服务密钥——Admin 用户可以在[团队设置](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**：你要查询的字段。请参阅下方的“可用字段”部分。

**NAME**：字段的别名。如果未指定，则默认为 \<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME> 的小写形式，例如 sum\_num\_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：你要查询的字段。请参阅“可用字段”部分。

NAME：该字段的别名。必须与所有其他字段名和聚合名称区分开。

<div id="available-fields">
  ## 可用字段
</div>

<div id="user-data">
  ### 用户数据
</div>

来自 USER\_DATA 数据源的所有数据都会按用户、按小时聚合。

注意：PCW (代码编写百分比) 现在有单独的表，不再依赖 user\_data 表。

| **字段名称**                   | **描述**                                           | **有效聚合方式**         |
| -------------------------- | ------------------------------------------------ | ------------------ |
| api\_key                   | 用户 API key 的哈希值。                                 | 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  | 去重后的 (用户，日期) 元组数。                                | UNSPECIFIED, COUNT |
| distinct\_developer\_hours | 去重后的 (用户，一天中的小时) 元组数。                            | UNSPECIFIED, COUNT |

<div id="chat-data">
  ### 聊天数据
</div>

注意，聊天数据 API 中提供的所有数据都针对聊天模型的响应，而不是用户提出的问题。

| **Field Name**             | **Description**                                                                                                                                                                                                                                                                                                                                                              | **Valid Aggregations** |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| api\_key                   | 用户 API key 的哈希值                                                                                                                                                                                                                                                                                                                                                              | 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">
  ### 命令数据
</div>

请注意，Command Data 数据源包含**所有**命令，包括被拒绝的命令。可使用 "accepted" 字段筛选出仅已接受的命令。

| **Field Name**   | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                            | **Valid Aggregations** |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| api\_key         | 用户 API key 的哈希值。                                                                                                                                                                                                                                                                                                                                                                                                                                                           | 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 表示常规命令用法。 | 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             |

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

<div id="valid-selections">
  #### 有效选项
</div>

| **字段名称**                         | **说明**                                                                                          | **有效聚合方式**  |
| -------------------------------- | ----------------------------------------------------------------------------------------------- | ----------- |
| 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      | 通过命令生成的 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 key 的哈希值。                                                                              | UNSPECIFIED, COUNT              |
| date                | 命令的 UTC 日期。                                                                                   | UNSPECIFIED, COUNT              |
| prompts\_used       | 发送到 Cascade 的提示所使用的提示积分数量，返回值以积分的百分之一为单位。例如，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>

|          |                                        |                   |
| -------- | -------------------------------------- | ----------------- |
| **字段名称** | **说明**                                 | **示例**            |
| api\_key | 用户 API key 的哈希值。                       |                   |
| 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 月整个月的总体代码编写百分比。示例响应 (为便于阅读，已格式化为 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
```

此查询显示按 IDE 分组的通过 "Generate Docstring" 代码透镜接受的代码行数 (全部时间) 。

响应示例：

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

<div id="command-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_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 (代码编写百分比) 数据，以及按 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>未检测到任何 selection 或 aggregation——请确保查询请求中至少包含一个。</td>
    </tr>

    <tr>
      <td>invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM</td>
      <td>某个 selection 使用了无效的聚合函数。在这个例子中，我们尝试对 "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>
        如果有多个 selection 字段，要么全部都包含 aggregation\_function，要么全部都不包含。例如，下面这个 selection 是无效的，因为 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。如果你想同时获取这两个字段的信息，请使用两个单独的查询。
      </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>所有 selection 和 aggregation 都必须使用不同的名称。请注意，如果未指定 name，默认会设置为 \<AGGREGATION\_FUNCTION>\_\<FIELD\_NAME>。</td>
    </tr>

    <tr>
      <td>invalid group name: GroupName</td>
      <td>未找到指定名称的组，请再次检查拼写。</td>
    </tr>
  </tbody>
</table>
