Skip to main content
GET
获取智能体工具调用分析数据
这是一个 v2 端点,使用 Bearer 令牌进行身份验证并通过查询参数传参;而 v1 分析 API 则是在请求体中传入服务密钥。详见下方的身份验证。
此端点不适用于实时用量监控。其速率限制较低 (每个团队每小时 10 次请求) ,请用于定期报告和批量导出。

身份验证

此端点使用 Bearer 令牌 进行身份验证。请在 Authorization 标头中提供您的令牌:
请使用具有 使用本地分析 API 权限的 Devin 服务用户 API 密钥,或具有 分析读取 权限的 Windsurf 服务密钥。有关这两种凭据的创建方法,请参阅 身份验证。 与 v1 的 cascade_tool_usage 数据源不同,此端点支持 Devin 服务用户 API 密钥,因此 Cognition 平台上的团队无需 Windsurf 服务密钥即可 获取工具使用情况报告。

指标

metric 查询参数为必填项,目前仅接受 calls,即智能体发起的工具调用次数。 该值以整数字段 calls 的形式出现在每一行中。如果请求未提供 metric 或指定了其他指标,将返回 400 错误。 无论使用哪个模型,只要智能体在 Devin Desktop 或 Devin CLI (包括在其他编辑器中作为智能体运行的 CLI) 中调用工具,均会计入工具调用次数。 product 参数同样为必填项,目前仅接受 agent。

工具

按 tool 分组,可按工具类别细分调用。此时每一行都会包含一个 tool 字段,其值为以下之一: 并非每个类别都适用于所有客户端:LIST_DIRECTORY、MEMORY、PROPOSE_CODE、 PROXY_WEB_SERVER、DEPLOY_WEB_APP 和 MQUERY 仅针对 Devin Desktop 智能体记录;尚未分配类别的新 Devin CLI 工具则计入 OTHER。

分组与粒度

使用 granularity 和 group_by 控制返回数据的结构:
  • 不设置粒度或分组 — 返回整个日期范围的单行聚合数据
  • granularity=daily — 每行包含 YYYY-MM-DD 格式的 timestamp
  • granularity=monthly — 每行包含 YYYY-MM 格式的 timestamp
  • group_by=tool — 每行包含 tool (参见上文的工具)
  • 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 中的 session 和 source 维度。 这里同样适用与 Get Consumption 相同的 models、group_id 和 user_id 过滤器,此外还支持 tool 过滤器, 用于将计数限定为某一种工具类别 (例如 tool=SEARCH_WEB) 。只有 此端点接受 tool;将其传给其他分析 API v2 端点会返回 400 错误。

示例

统计一周内每个用户的网页搜索次数:
每一行表示一个用户的 SEARCH_WEB 次数。若要改为查看每个用户的所有类别,请去掉 tool 过滤器,并添加 group_by=user,tool。

分页

结果以分页形式返回,默认每页 1,000 行 (最多 10,000 行) 。如果还有更多结果, 响应会在 pagination 对象中返回 next_page_cursor。请在后续请求中将其作为 page_cursor 查询 参数传入,其余查询参数与原始请求保持一致。游标仅对签发它的端点有效;来自 /consumption 或 /output 的游标 会被拒绝,并返回 400。 页面游标的有效期为 24 小时。获取后续分页的请求不会计为新的 query,也不会占用您的速率限制。

速率限制

此端点的速率限制为每个团队每小时 10 次请求。超出此限制时, 服务器将返回 429 Too Many Requests,并附带 Retry-After 标头。 对先前的查询进行分页 (即使用 next_page_cursor 继续获取结果) 不计入此限制, 只有每份报告的首次查询才会计入。之所以限制较低,是因为该端点用于 定期报告,而非实时用量监控。

授权

Authorization
string
header
必填

需要一个具有 Analytics Read 权限的服务密钥,并通过 Authorization 标头以 Bearer 令牌的形式传递。

你可以在团队设置中的“Service Keys”部分创建服务密钥。

查询参数

metric
string
必填

要返回的指标,以字段形式出现在每行中。支持的指标:

  • calls — 智能体的工具调用次数
start_date
string<date>
必填

日期范围的开始日期(含当日),格式为 YYYY-MM-DD。

end_date
string<date>
必填

日期范围的结束日期(含当日),格式为 YYYY-MM-DD。日期范围不得超过 90 天。

product
enum<string>
必填

要查询其工具调用数据的产品。

可用选项:
agent
granularity
enum<string>

用于对结果分组的时间粒度。指定后,每行都包含一个 timestamp 字段。 如果省略,则汇总整个日期范围内的结果。

可用选项:
daily,
monthly
group_by
string

用于对结果分组的维度列表,以逗号分隔。支持的维度:

  • tool — 每行包含 tool(工具类别,例如 SEARCH_WEB 或 RUN_COMMAND)
  • user — 每行包含 user_id;如果记录了该用户的电子邮件地址,还会包含 user_email
  • model_uid — 每行包含 model_uid
  • ide — 每行包含 ide
  • ide_version — 每行包含 ide_version;必须同时包含 ide
  • os — 每行包含 os
models
string

用于过滤结果的模型 UID 列表,以逗号分隔。

tool
string

仅统计一个工具类别,例如 SEARCH_WEB 或 RUN_COMMAND(精确匹配)。 仅此端点接受该参数。

group_id
string

仅返回指定组中用户的结果。服务密钥必须具有该组的访问权限。不支持使用 Devin 服务用户 API 密钥。

user_id
string

仅返回指定用户(身份验证 UID)的结果。

page_size
integer
默认值:1000

每页返回的最大行数。

必填范围: 1 <= x <= 10000
page_cursor
string

上一个响应中 pagination.next_page_cursor 返回的不透明游标,用于获取下一页。传入的 metric 必须与生成该游标的请求中使用的值相同;其他端点生成的游标将被拒绝。

响应

已成功返回工具调用数据。

data
object[]
必填

工具调用数据行组成的数组。

pagination
object
必填
metadata
object
必填