自定义 Analytics 查询

概览

Custom Analytics API 为 Autocomplete、Chat 和 Command 的数据提供灵活的查询功能，支持自定义 selections、过滤器、aggregations 和排序。

请求

service_key

string

必填

您的服务密钥，需具备“Teams Read-only”权限

group_name

string

将结果限定为特定用户组内的用户（可选）

query_requests

array

必填

用于定义要检索数据的查询请求对象数组

查询请求结构

每个查询请求对象包含：

data_source

string

必填

要查询的数据源。可选值：

QUERY_DATA_SOURCE_USER_DATA - Autocomplete 数据
QUERY_DATA_SOURCE_CHAT_DATA - Chat 数据
QUERY_DATA_SOURCE_COMMAND_DATA - Command 数据
QUERY_DATA_SOURCE_PCW_DATA - Percent Code Written 数据

selections

array

必填

要检索的字段 selections 数组（参见 Selections 章节）

filters

array

要应用的过滤条件数组（参见 Filters 章节）

aggregations

array

用于分组的 aggregations 数组（参见 Aggregations 章节）

selections

selections 用于定义要检索的字段以及对这些字段进行聚合的方式。

field

string

必填

要选择的字段名称（参见“Available Fields”部分）

name

string

字段的别名。若未指定，默认采用 {aggregation_function}_{field_name}（小写）

aggregation_function

string

要应用的聚合函数：

QUERY_AGGREGATION_UNSPECIFIED（默认）
QUERY_AGGREGATION_COUNT
QUERY_AGGREGATION_SUM
QUERY_AGGREGATION_AVG
QUERY_AGGREGATION_MAX
QUERY_AGGREGATION_MIN

选择示例

{
  "field": "num_acceptances",
  "name": "total_acceptances",
  "aggregation_function": "QUERY_AGGREGATION_SUM"
}

过滤器

过滤器用于将数据限定为符合特定条件的元素。

name

string

必填

要过滤的字段名

value

string

必填

用于比较的值

filter

string

必填

过滤操作：

QUERY_FILTER_EQUAL
QUERY_FILTER_NOT_EQUAL
QUERY_FILTER_GREATER_THAN
QUERY_FILTER_LESS_THAN
QUERY_FILTER_GE（大于等于）
QUERY_FILTER_LE（小于等于）

过滤示例

{
  "name": "language",
  "filter": "QUERY_FILTER_EQUAL",
  "value": "PYTHON"
}

Aggregations

Aggregations 用于按指定条件对数据进行分组。

field

string

必填

用于分组的字段名

name

string

必填

该聚合字段的别名

聚合示例

{
  "field": "ide",
  "name": "ide_type"
}

可用字段

用户数据

所有用户数据按“每位用户、每小时”进行聚合。

字段名称	描述	可用聚合
`api_key`	用户 API 密钥的哈希值	UNSPECIFIED, COUNT
`date`	自动补全的 UTC 日期	UNSPECIFIED, COUNT
`date UTC-x`	带时区偏移的日期（例如，“date UTC-8”表示 PST）	UNSPECIFIED, COUNT
`hour`	自动补全的 UTC 小时	UNSPECIFIED, COUNT
`language`	编程语言	UNSPECIFIED, COUNT
`ide`	使用的 IDE	UNSPECIFIED, COUNT
`version`	Windsurf 版本	UNSPECIFIED, COUNT
`num_acceptances`	Autocomplete 接受次数	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

Chat 数据

Chat 数据与 Cascade 数据相互独立，表示我们旧版、非代理式插件的使用情况

所有 Chat 数据指的是 Chat AI 模型的回复，而非用户提问。

Field Name	Description	Valid Aggregations
`api_key`	用户 API 密钥的哈希值	UNSPECIFIED, COUNT
`model_id`	Chat 模型 ID	UNSPECIFIED, COUNT
`date`	Chat 回复的 UTC 日期	UNSPECIFIED, COUNT
`date UTC-x`	带时区偏移的日期	UNSPECIFIED, COUNT
`ide`	使用的 IDE	UNSPECIFIED, COUNT
`version`	Windsurf 版本	UNSPECIFIED, COUNT
`latest_intent_type`	Chat 意图类型（见下文“意图类型”）	UNSPECIFIED, COUNT
`num_chats_received`	接收的聊天消息数量	SUM, MAX, MIN, AVG
`chat_accepted`	是否接受该聊天（点赞）	SUM, COUNT
`chat_inserted_at_cursor`	是否点击“Insert”按钮	SUM, COUNT
`chat_applied`	是否点击“Apply Diff”按钮	SUM, COUNT
`chat_loc_used`	来自 Chat 的使用代码行数	SUM, MAX, MIN, AVG

Chat 意图类型

CHAT_INTENT_GENERIC - 常规 Chat
CHAT_INTENT_FUNCTION_EXPLAIN - 函数解释 code lens
CHAT_INTENT_FUNCTION_DOCSTRING - 函数文档字符串 code lens
CHAT_INTENT_FUNCTION_REFACTOR - 函数重构 code lens
CHAT_INTENT_CODE_BLOCK_EXPLAIN - 代码块解释 code lens
CHAT_INTENT_CODE_BLOCK_REFACTOR - 代码块重构 code lens
CHAT_INTENT_PROBLEM_EXPLAIN - 问题解释 code lens
CHAT_INTENT_FUNCTION_UNIT_TESTS - 函数单元测试 code lens

Command 数据

Command 数据包含所有命令，包括被拒绝的。使用 accepted 字段仅筛选已接受的命令。

字段名称	描述	可用聚合
`api_key`	用户 API 密钥的哈希值	UNSPECIFIED, COUNT
`date`	命令的 UTC 日期	UNSPECIFIED, COUNT
`timestamp`	命令的 UTC 时间戳	UNSPECIFIED, COUNT
`language`	编程语言	UNSPECIFIED, COUNT
`ide`	使用的 IDE	UNSPECIFIED, COUNT
`version`	Windsurf 版本	UNSPECIFIED, COUNT
`command_source`	Command 触发来源（见下文 Command Sources）	UNSPECIFIED, COUNT
`provider_source`	生成或编辑模式	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`	选中的行数（生成时为 0）	SUM, MAX, MIN, AVG
`selection_bytes`	选中的字节数（生成时为 0）	SUM, MAX, MIN, AVG
`accepted`	命令是否被接受	SUM, COUNT

Command 来源

COMMAND_REQUEST_SOURCE_LINE_HINT_CODE_LENS
COMMAND_REQUEST_SOURCE_DEFAULT - 典型的 Command 用法
COMMAND_REQUEST_SOURCE_RIGHT_CLICK_REFACTOR
COMMAND_REQUEST_SOURCE_FUNCTION_CODE_LENS
COMMAND_REQUEST_SOURCE_FOLLOWUP
COMMAND_REQUEST_SOURCE_CLASS_CODE_LENS
COMMAND_REQUEST_SOURCE_PLAN
COMMAND_REQUEST_SOURCE_SELECTION_HINT_CODE_LENS

提供方来源

PROVIDER_SOURCE_COMMAND_GENERATE - 生成模式
PROVIDER_SOURCE_COMMAND_EDIT - 编辑模式

PCW 数据

“代码编写占比”（Percent Code Written）数据，并分别统计 Autocomplete 与 Command 的贡献。

Field Name	Description	Valid Aggregations
`percent_code_written`	计算为 codeium_bytes / (codeium_bytes + user_bytes)	UNSPECIFIED
`codeium_bytes`	由 Codeium 生成的总字节数	UNSPECIFIED
`user_bytes`	由用户编写的总字节数	UNSPECIFIED
`total_bytes`	codeium_bytes + user_bytes	UNSPECIFIED
`codeium_bytes_by_autocomplete`	来自 Autocomplete 的 Codeium 字节数	UNSPECIFIED
`codeium_bytes_by_command`	来自 Command 的 Codeium 字节数	UNSPECIFIED

PCW 筛选项

字段名	说明	示例
`language`	编程语言	KOTLIN, GO, JAVA
`ide`	所用 IDE	jetbrains, vscode
`version`	Windsurf 版本	1.28.0, 130.0

在 PCW 查询中进行日期过滤时，请在主请求体中使用 start_timestamp 和 end_timestamp。

示例请求

用户数据示例

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": "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

Chat 数据示例

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

Command 数据示例

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

PCW 数据示例

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

响应

queryResults

array

查询结果数组，每个查询请求对应一个结果

responseItems

array

结果项数组

item

object

包含所选字段及其值的对象

示例回复

用户数据响应

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "total_acceptances": "125",
            "total_lines": "863"
          }
        }
      ]
    }
  ]
}

Chat 数据响应

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "lines_used": "74",
            "ide_type": "jetbrains"
          }
        },
        {
          "item": {
            "lines_used": "41",
            "ide_type": "vscode"
          }
        }
      ]
    }
  ]
}

Command 数据响应

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

PCW 数据响应

{
  "queryResults": [
    {
      "responseItems": [
        {
          "item": {
            "ai_bytes": "6018",
            "autocomplete_bytes": "4593",
            "command_bytes": "1425",
            "pcw": "0.61",
            "total": "9900"
          }
        }
      ]
    }
  ]
}

重要说明

PCW（Percent Code Written，代码编写占比）在单日或单个用户层面波动较大——按周汇总能获得更稳健的洞察
所有被选字段要么全部使用聚合函数，要么全部不使用（不可混用）
符合 “distinct_*” 模式的字段不能用于 aggregations
字段别名在所有 selections 和 aggregations 中必须唯一
如未指定聚合函数，将默认为 UNSPECIFIED

编辑器

Cascade

账户

上下文感知

故障排查

安全

自定义 Analytics 查询

概览

请求

查询请求结构

selections

选择示例

过滤器

过滤示例

Aggregations

聚合示例

可用字段

用户数据

Chat 数据

Chat 意图类型

Command 数据

Command 来源

提供方来源

PCW 数据

PCW 筛选项

示例请求

用户数据示例

Chat 数据示例

Command 数据示例

PCW 数据示例

响应

示例回复

用户数据响应

Chat 数据响应

Command 数据响应

PCW 数据响应

重要说明

编辑器

Cascade

账户

上下文感知

故障排查

安全

​概览

​请求

​查询请求结构

​selections

​选择示例

​过滤器

​过滤示例

​Aggregations

​聚合示例

​可用字段

​用户数据

​Chat 数据

​Chat 意图类型

​Command 数据

​Command 来源

​提供方来源

​PCW 数据

​PCW 筛选项

​示例请求

​用户数据示例

​Chat 数据示例

​Command 数据示例

​PCW 数据示例

​响应

​示例回复

​用户数据响应

​Chat 数据响应

​Command 数据响应

​PCW 数据响应

​重要说明

概览

请求

查询请求结构

selections

选择示例

过滤器

过滤示例

Aggregations

聚合示例

可用字段

用户数据

Chat 数据

Chat 意图类型

Command 数据

Command 来源

提供方来源

PCW 数据

PCW 筛选项

示例请求

用户数据示例

Chat 数据示例

Command 数据示例

PCW 数据示例

响应

示例回复

用户数据响应

Chat 数据响应

Command 数据响应

PCW 数据响应

重要说明