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

# 获取 Cascade 分析数据

> 查询 Cascade 专属的用量指标，包括建议/采纳的代码行数、模型用量、额度消耗以及工具用量统计。

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

获取 Cascade 特有的分析数据，包括建议和采纳的代码行数、模型用量、额度消耗以及工具用量统计。

<div id="request">
  ## 请求
</div>

<ParamField body="service_key" type="string" required>
  具有“Teams 只读”权限的服务密钥
</ParamField>

<ParamField body="group_name" type="string">
  将结果筛选为特定组中的用户。不能与 `emails` 参数同时使用。
</ParamField>

<ParamField body="start_timestamp" type="string">
  开始时间，采用 RFC 3339 格式 (例如 `2023-01-01T00:00:00Z`)
</ParamField>

<ParamField body="end_timestamp" type="string">
  结束时间，采用 RFC 3339 格式 (例如 `2023-12-31T23:59:59Z`)
</ParamField>

<ParamField body="emails" type="array">
  用于筛选结果的电子邮件地址数组。不能与 `group_name` 参数同时使用。
</ParamField>

<ParamField body="ide_types" type="array">
  按 IDE 类型筛选。可用选项：

  * `"editor"` - Devin Desktop Editor
  * `"jetbrains"` - JetBrains Plugin
  * `"cli"` - Devin CLI

  如果省略，则返回所有 IDE 的数据。

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

<ParamField body="query_requests" type="array" required>
  要执行的数据源查询数组。每个对象都应包含一个受支持的数据源。
</ParamField>

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

<div id="cascade_lines">
  ### cascade\_lines
</div>

查询 Cascade 每日建议及已接受的代码行数。

```json theme={null}
{
  "cascade_lines": {}
}
```

**响应字段：**

* `day` - RFC 3339 格式的日期
* `linesSuggested` - 建议的代码行数
* `linesAccepted` - 已接受的代码行数

<div id="cascade_runs">
  ### cascade\_runs
</div>

查询模型用量、额度消耗和模式数据。

```json theme={null}
{
  "cascade_runs": {}
}
```

**响应字段：**

* `day` - RFC 3339 格式的日期
* `model` - 所使用的模型名称
* `mode` - Cascade 模式 (参见下方模式说明)
* `messagesSent` - 已发送的消息数
* `cascadeId` - 唯一对话 ID
* `promptsUsed` - 已消耗的额度 (单位：美分)

**Cascade 模式：**

* `CONVERSATIONAL_PLANNER_MODE_DEFAULT` - 编写模式
* `CONVERSATIONAL_PLANNER_MODE_READ_ONLY` - 只读模式
* `CONVERSATIONAL_PLANNER_MODE_NO_TOOL` - 旧版模式
* `UNKNOWN` - 未知模式

<div id="cascade_tool_usage">
  ### cascade\_tool\_usage
</div>

查询工具用量统计 (汇总计数) 。

```json theme={null}
{
  "cascade_tool_usage": {}
}
```

**响应字段：**

* `tool` - 工具标识符 (参见下方的工具映射)
* `count` - 工具使用的次数

<div id="tool-usage-mappings">
  ## 工具用量映射
</div>

| 工具标识符               | 显示名称       |
| ------------------- | ---------- |
| `CODE_ACTION`       | 代码编辑       |
| `VIEW_FILE`         | 查看文件       |
| `RUN_COMMAND`       | 运行命令       |
| `FIND`              | 查找工具       |
| `GREP_SEARCH`       | Grep 搜索    |
| `VIEW_FILE_OUTLINE` | 文件大纲       |
| `MQUERY`            | Riptide    |
| `WORKFLOWS_USED`    | 所用工作流程     |
| `LIST_DIRECTORY`    | 列出目录       |
| `MCP_TOOL`          | MCP 工具     |
| `PROPOSE_CODE`      | 建议代码       |
| `SEARCH_WEB`        | 搜索 Web     |
| `MEMORY`            | 记忆         |
| `PROXY_WEB_SERVER`  | Browser 预览 |
| `DEPLOY_WEB_APP`    | 部署 Web 应用  |

<div id="example-request">
  ## 请求示例
</div>

```bash theme={null}
curl -X POST --header "Content-Type: application/json" \
--data '{
  "service_key": "your_service_key_here",
  "group_name": "engineering_team",
  "start_timestamp": "2025-01-01T00:00:00Z",
  "end_timestamp": "2025-01-02T00:00:00Z",
  "emails": ["user1@cognition.ai", "user2@cognition.ai"],
  "ide_types": ["editor"],
  "query_requests": [
    {
      "cascade_lines": {}
    },
    {
      "cascade_runs": {}
    },
    {
      "cascade_tool_usage": {}
    }
  ]
}' \
https://server.codeium.com/api/v1/CascadeAnalytics
```

<div id="response">
  ## 响应
</div>

<ResponseField name="queryResults" type="array">
  查询结果数组，每个查询请求对应一个结果

  <Expandable title="Cascade 代码行结果">
    <ResponseField name="cascadeLines" type="object">
      <ResponseField name="cascadeLines" type="array">
        每日代码行统计数组

        <ResponseField name="day" type="string">
          RFC 3339 格式的日期
        </ResponseField>

        <ResponseField name="linesSuggested" type="string">
          当天建议的代码行数
        </ResponseField>

        <ResponseField name="linesAccepted" type="string">
          当天接受的代码行数
        </ResponseField>
      </ResponseField>
    </ResponseField>
  </Expandable>

  <Expandable title="Cascade 运行结果">
    <ResponseField name="cascadeRuns" type="object">
      <ResponseField name="cascadeRuns" type="array">
        模型用量统计数组

        <ResponseField name="day" type="string">
          RFC 3339 格式的日期
        </ResponseField>

        <ResponseField name="model" type="string">
          此次运行使用的模型名称
        </ResponseField>

        <ResponseField name="mode" type="string">
          Cascade 模式标识符
        </ResponseField>

        <ResponseField name="messagesSent" type="string">
          已发送的消息数
        </ResponseField>

        <ResponseField name="cascadeId" type="string">
          唯一会话标识符
        </ResponseField>

        <ResponseField name="promptsUsed" type="string">
          按美分计的已消耗额度 (例如：“100” = 1 个额度)
        </ResponseField>
      </ResponseField>
    </ResponseField>
  </Expandable>

  <Expandable title="Cascade 工具用量结果">
    <ResponseField name="cascadeToolUsage" type="object">
      <ResponseField name="cascadeToolUsage" type="array">
        工具用量统计数组

        <ResponseField name="tool" type="string">
          工具标识符
        </ResponseField>

        <ResponseField name="count" type="string">
          工具使用次数
        </ResponseField>
      </ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="example-response">
  ### 响应示例
</div>

```json theme={null}
{
  "queryResults": [
    {
      "cascadeLines": {
        "cascadeLines": [
          {
            "day": "2025-05-01T00:00:00Z",
            "linesSuggested": "206",
            "linesAccepted": "157"
          },
          {
            "day": "2025-05-02T00:00:00Z",
            "linesSuggested": "16"
          }
        ]
      }
    },
    {
      "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"
          }
        ]
      }
    },
    {
      "cascadeToolUsage": {
        "cascadeToolUsage": [
          {
            "tool": "CODE_ACTION",
            "count": "15"
          },
          {
            "tool": "LIST_DIRECTORY",
            "count": "20"
          }
        ]
      }
    }
  ]
}
```

<div id="notes">
  ## 注意事项
</div>

* API 返回原始数据，其中可能包含 `"UNKNOWN"` 值
* 进行指标分析时，请按关注的特定字段聚合 (例如，对 `promptsUsed` 求和以分析用量模式)
* 模式和提示数据可能会分散在多个条目中
* 额度消耗 (`promptsUsed`) 以分为单位返回 (100 = 1 积分)