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

# 获取 Devin 智能体工具调用

> 统计您的团队在 Devin Desktop 和 Devin CLI 中发起的智能体工具调用（如网页搜索、运行命令）次数，可按工具、用户、模型、IDE 或操作系统分组。

<Note>
  这是一个 **v2 端点**，使用 Bearer 令牌进行身份验证并通过查询参数传参；而 v1 分析 API 则是在请求体中传入服务密钥。详见下方的[身份验证](#authentication)。
</Note>

<Warning>
  此端点**不**适用于实时用量监控。其速率限制较低
  (每个团队每小时 10 次请求) ，请用于定期报告和批量导出。
</Warning>

<h2 id="authentication">
  身份验证
</h2>

此端点使用 **Bearer 令牌** 进行身份验证。请在 `Authorization` 标头中提供您的令牌：

```
Authorization: Bearer <your_token>
```

请使用具有 **使用本地分析 API** 权限的 Devin 服务用户 API 密钥，或具有 **分析读取** 权限的 Windsurf
服务密钥。有关这两种凭据的创建方法，请参阅
[身份验证](/zh/desktop/accounts/api-reference/analytics-v2-introduction#authentication)。

与 v1 的 [`cascade_tool_usage`](/zh/desktop/accounts/api-reference/cascade-analytics#cascade_tool_usage)
数据源不同，此端点支持 Devin 服务用户 API 密钥，因此 Cognition 平台上的团队无需 Windsurf 服务密钥即可
获取工具使用情况报告。

<h2 id="metrics">
  指标
</h2>

`metric` 查询参数为必填项，目前仅接受 `calls`，即智能体发起的工具调用次数。
该值以整数字段 `calls` 的形式出现在每一行中。如果请求未提供 `metric` 或指定了其他指标，将返回 `400` 错误。

无论使用哪个模型，只要智能体在 [Devin Desktop](/zh/desktop/introducing-devin-desktop)
或 [Devin CLI](/zh/cli) (包括在其他编辑器中作为智能体运行的 CLI) 中调用工具，均会计入工具调用次数。
`product` 参数同样为必填项，目前仅接受 `agent`。

<h2 id="tools">
  工具
</h2>

按 `tool` 分组，可按工具类别细分调用。此时每一行都会包含一个 `tool` 字段，其值为以下之一：

| 工具 | 描述 |
| - | - |
| `SEARCH_WEB` | 网页搜索、网页抓取和浏览器操作 |
| `RUN_COMMAND` | Shell 命令以及与运行中进程的交互 |
| `VIEW_FILE` | 读取文件和笔记本 |
| `CODE_ACTION` | 编辑、写入和修补文件 |
| `GREP_SEARCH` | 搜索文件内容和代码 |
| `FIND` | 按名称查找文件 |
| `LIST_DIRECTORY` | 列出目录 |
| `MCP_TOOL` | 调用 MCP 服务器工具，以及列出 MCP 服务器、工具或资源 |
| `SKILL` | 列出、搜索和调用技能 |
| `ASK_USER_QUESTION` | 向用户提问 |
| `MEMORY` | 读取和写入记忆 |
| `PROPOSE_CODE` | 提出代码修改建议 |
| `PROXY_WEB_SERVER` | 在浏览器中预览本地 Web 服务器 |
| `DEPLOY_WEB_APP` | 部署 Web 应用 |
| `MQUERY` | 代码库搜索 (Riptide) |
| `DEEPWIKI` | DeepWiki 请求 |
| `CODEMAP_GENERATION`、`CODEMAP_SUGGESTIONS` | Codemaps 请求 |
| `OTHER` | 不属于上述类别的 Devin CLI 工具 |

并非每个类别都适用于所有客户端：`LIST_DIRECTORY`、`MEMORY`、`PROPOSE_CODE`、
`PROXY_WEB_SERVER`、`DEPLOY_WEB_APP` 和 `MQUERY` 仅针对 Devin Desktop 智能体记录；尚未分配类别的新
Devin CLI 工具则计入 `OTHER`。

<h2 id="grouping-and-granularity">
  分组与粒度
</h2>

使用 `granularity` 和 `group_by` 控制返回数据的结构：

* **不设置粒度或分组** — 返回整个日期范围的单行聚合数据
* **`granularity=daily`** — 每行包含 `YYYY-MM-DD` 格式的 `timestamp`
* **`granularity=monthly`** — 每行包含 `YYYY-MM` 格式的 `timestamp`
* **`group_by=tool`** — 每行包含 `tool` (参见上文的[工具](#tools))
* **`group_by=user`** — 每行包含 `user_id`；如果该用户有记录的邮箱，还会包含 `user_email`
* **`group_by=model_uid`** — 每行包含 `model_uid`
* **`group_by=ide`** — 每行包含 `ide`
* **`group_by=ide,ide_version`** — 每行包含 `ide` 和 `ide_version` (按 `ide_version` 分组时必须同时包含 `ide`)
* **`group_by=os`** — 每行包含 `os`，例如 `darwin` (macOS) 、`windows` 或 `linux`

各维度可以组合使用，例如 `group_by=user,tool` 会统计每个用户调用每种
工具的次数。此处不支持 [Get Output](/zh/desktop/accounts/api-reference/get-output) 中的 `session` 和 `source` 维度。
这里同样适用与 [Get Consumption](/zh/desktop/accounts/api-reference/get-consumption) 相同的 `models`、`group_id` 和 `user_id` 过滤器，此外还支持 `tool` 过滤器，
用于将计数限定为某一种工具类别 (例如 `tool=SEARCH_WEB`) 。只有
此端点接受 `tool`；将其传给其他分析 API v2 端点会返回 `400` 错误。

<h2 id="example">
  示例
</h2>

统计一周内每个用户的网页搜索次数：

```bash theme={null}
curl "https://server.codeium.com/api/v2alpha/analytics/tools?metric=calls&product=agent&start_date=2026-10-13&end_date=2026-10-19&group_by=user&tool=SEARCH_WEB" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

每一行表示一个用户的 `SEARCH_WEB` 次数。若要改为查看每个用户的所有类别，请去掉 `tool` 过滤器，并添加 `group_by=user,tool`。

<h2 id="pagination">
  分页
</h2>

结果以分页形式返回，默认每页 1,000 行 (最多 10,000 行) 。如果还有更多结果，
响应会在 `pagination` 对象中返回 `next_page_cursor`。请在后续请求中将其作为 `page_cursor` 查询
参数传入，其余查询参数与原始请求保持一致。游标仅对签发它的端点有效；来自 `/consumption` 或 `/output` 的游标
会被拒绝，并返回 `400`。

页面游标的有效期为 24 小时。获取后续分页的请求不会计为新的 query，也不会占用您的速率限制。

<h2 id="rate-limits">
  速率限制
</h2>

此端点的速率限制为每个团队**每小时 10 次请求**。超出此限制时，
服务器将返回 `429 Too Many Requests`，并附带 `Retry-After` 标头。

对先前的查询进行分页 (即使用 `next_page_cursor` 继续获取结果) **不**计入此限制，
只有每份报告的首次查询才会计入。之所以限制较低，是因为该端点用于
定期报告，而非实时用量监控。


## OpenAPI

````yaml zh/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/tools
openapi: 3.1.0
info:
  title: Devin Desktop Analytics API v2
  version: 2.0.0
  description: |
    分析 API v2 为企业团队提供积分和 ACU 用量、活跃用户、智能体输出
    (已接受的代码行数)，以及智能体工具调用分析。数据来自
    按小时聚合的结果，并支持灵活筛选、分组和基于游标的分页。
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/tools:
    get:
      summary: 获取智能体工具调用分析数据
      description: |
        统计已通过身份验证的团队的智能体工具调用次数。必填参数 `metric` 仅接受
        `calls`，表示智能体在 Devin Desktop 和 Devin CLI 中的工具调用次数，并在每行中以
        整数字段返回。结果可按日期范围、产品、模型、组和用户过滤，
        并可按与用量相同的维度（`session` 除外）以及 `tool` 分组，其中 `tool` 表示工具类别，
        例如 `SEARCH_WEB` 或 `RUN_COMMAND`。

        这些端点专为定期报告和批量导出而设计，**不**适用于实时用量监控：速率限制较低（每个团队每小时 10 次请求）。
      operationId: getTools
      parameters:
        - name: metric
          in: query
          required: true
          schema:
            type: string
          description: |
            要返回的指标，以字段形式出现在每行中。支持的指标：
            - `calls` — 智能体的工具调用次数
          example: calls
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: 日期范围的开始日期（含当日），格式为 `YYYY-MM-DD`。
          example: '2026-10-01T00:00:00.000Z'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: 日期范围的结束日期（含当日），格式为 `YYYY-MM-DD`。日期范围不得超过 90 天。
          example: '2026-10-31T00:00:00.000Z'
        - name: product
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: 要查询其工具调用数据的产品。
          example: agent
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - monthly
          description: |
            用于对结果分组的时间粒度。指定后，每行都包含一个 `timestamp` 字段。
            如果省略，则汇总整个日期范围内的结果。
        - name: group_by
          in: query
          required: false
          schema:
            type: string
          description: |
            用于对结果分组的维度列表，以逗号分隔。支持的维度：
            - `tool` — 每行包含 `tool`（工具类别，例如 `SEARCH_WEB` 或 `RUN_COMMAND`）
            - `user` — 每行包含 `user_id`；如果记录了该用户的电子邮件地址，还会包含 `user_email`
            - `model_uid` — 每行包含 `model_uid`
            - `ide` — 每行包含 `ide`
            - `ide_version` — 每行包含 `ide_version`；必须同时包含 `ide`
            - `os` — 每行包含 `os`
          example: user,tool
        - name: models
          in: query
          required: false
          schema:
            type: string
          description: 用于过滤结果的模型 UID 列表，以逗号分隔。
          example: swe-2-high,claude-4-sonnet
        - name: tool
          in: query
          required: false
          schema:
            type: string
          description: |
            仅统计一个工具类别，例如 `SEARCH_WEB` 或 `RUN_COMMAND`（精确匹配）。
            仅此端点接受该参数。
          example: SEARCH_WEB
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: 仅返回指定组中用户的结果。服务密钥必须具有该组的访问权限。不支持使用 Devin 服务用户 API 密钥。
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: 仅返回指定用户（身份验证 UID）的结果。
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          description: 每页返回的最大行数。
        - name: page_cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            上一个响应中 `pagination.next_page_cursor` 返回的不透明游标，用于获取下一页。传入的 `metric`
            必须与生成该游标的请求中使用的值相同；其他端点生成的游标将被拒绝。
      responses:
        '200':
          description: 已成功返回工具调用数据。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolsResponse'
              examples:
                by_user_tool:
                  summary: 每位用户的网页搜索和命令
                  value:
                    data:
                      - user_id: user_abc123
                        user_email: alice@example.com
                        tool: RUN_COMMAND
                        calls: 1842
                      - user_id: user_abc123
                        user_email: alice@example.com
                        tool: SEARCH_WEB
                        calls: 57
                    pagination:
                      next_page_cursor: null
                    metadata:
                      data_freshness: '2026-10-20T02:00:00.000Z'
                      query_time_ms: 1104
                      team_id: team_abc123
                daily_total:
                  summary: granularity=daily 且不分组
                  value:
                    data:
                      - timestamp: '2026-10-13T00:00:00.000Z'
                        calls: 48210
                      - timestamp: '2026-10-14T00:00:00.000Z'
                        calls: 51377
                    pagination:
                      next_page_cursor: null
                    metadata:
                      data_freshness: '2026-10-20T02:00:00.000Z'
                      query_time_ms: 870
                      team_id: team_abc123
        '400':
          description: 请求参数无效。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_metric:
                  value:
                    error: metric is required
                bad_metric:
                  value:
                    error: 'unsupported metric: loc_inserted (supported: calls)'
                missing_product:
                  value:
                    error: product is required
                bad_group_by:
                  value:
                    error: 'unsupported group_by dimension for tools: session'
        '401':
          description: 身份验证失败或权限不足。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_auth:
                  value:
                    error: missing Authorization header
                invalid_key:
                  value:
                    error: invalid service key
                insufficient_permissions:
                  value:
                    error: insufficient permissions
        '403':
          description: 提供的页面游标不属于已通过身份验证的团队或请求中指定的组。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                cursor_team_mismatch:
                  value:
                    error: page cursor does not belong to this team
        '405':
          description: 不允许使用此 HTTP 方法（仅支持 `GET`）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 超出速率限制（每个团队每小时 10 次请求）。对先前 query 的分页请求不计入此限制。
          headers:
            Retry-After:
              schema:
                type: string
              description: 建议在重试前等待的时间。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: rate limit exceeded
        '503':
          description: 分析服务不可用（例如，在自托管部署中）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    ToolsResponse:
      type: object
      required:
        - data
        - pagination
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ToolsRow'
          description: 工具调用数据行组成的数组。
        pagination:
          type: object
          properties:
            next_page_cursor:
              type:
                - string
                - 'null'
              description: |
                用于获取下一页结果的不透明游标。在后续请求中将此值作为 `page_cursor`
                查询参数传递。没有更多页面时为 `null`。
                页面游标在 24 小时后过期。
        metadata:
          type: object
          properties:
            data_freshness:
              type: string
              format: date-time
              description: 底层数据上次刷新的时间戳（截断至整点）。
            query_time_ms:
              type: integer
              format: int64
              description: 服务端 query 执行时间，以毫秒为单位。
            team_id:
              type: string
              description: 从已通过身份验证的服务密钥解析出的团队 ID。
            group_id:
              type: string
              description: 结果所属的组 ID。仅在提供 `group_id` 时出现。
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: 便于人工阅读的错误消息。
    ToolsRow:
      type: object
      required:
        - calls
      properties:
        timestamp:
          type: string
          description: |
            该行对应的时间分桶。格式取决于 `granularity`：按天为 `YYYY-MM-DD`，按月为 `YYYY-MM`。
            仅在指定 `granularity` 时出现。
          examples:
            - '2026-10-15T00:00:00.000Z'
            - 2026-10
        user_id:
          type: string
          description: 用户标识符（身份验证 UID）。仅当 `group_by` 包含 `user` 时出现。
        user_email:
          type: string
          description: 用户的电子邮件地址。仅当 `group_by` 包含 `user` 且已记录该用户的电子邮件地址时出现。
          examples:
            - alice@example.com
        model_uid:
          type: string
          description: 模型标识符。仅当 `group_by` 包含 `model_uid` 时出现。
          examples:
            - swe-2-high
        ide:
          type: string
          description: IDE 名称。仅当 `group_by` 包含 `ide` 时出现。
          examples:
            - windsurf
            - devin-cli
        ide_version:
          type: string
          description: IDE 版本。仅当 `group_by` 包含 `ide_version` 时出现（还需包含 `ide`）。
          examples:
            - 3000.10.48
        os:
          type: string
          description: 发起请求的操作系统。仅当 `group_by` 包含 `os` 时出现。
          examples:
            - darwin
            - windows
            - linux
        tool:
          type: string
          description: >
            所调用工具的类别，例如 `SEARCH_WEB`、`RUN_COMMAND`、`VIEW_FILE`、

            `CODE_ACTION`、`GREP_SEARCH`、`FIND`、`MCP_TOOL`、`SKILL` 或
            `ASK_USER_QUESTION`。未分类的 Devin CLI 工具

            归为 `OTHER`。仅当 `group_by` 包含 `tool` 时出现。
          examples:
            - SEARCH_WEB
            - RUN_COMMAND
        calls:
          type: integer
          format: int64
          description: 该行中的智能体工具调用次数。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        需要一个具有 **Analytics Read** 权限的服务密钥，并通过 `Authorization` 标头以 Bearer
        令牌的形式传递。


        你可以在[团队设置](https://windsurf.com/team/settings)中的“Service Keys”部分创建服务密钥。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.