跳转到主要内容
GET
获取用量分析
这是一个v2 端点,使用 Bearer 令牌身份验证和查询参数;不同于 v1 分析 API,后者在请求体中使用服务密钥。请参阅下方的身份验证
此端点适用于实时用量监控。数据按小时聚合,且 速率限制较低 (每个团队每小时 10 个请求) 。请将其用于定期报告和批量导出。

身份验证

此端点使用 Bearer 令牌 进行身份验证。请在 Authorization 标头中包含你的服务密钥:
服务密钥必须具备 Analytics Read 权限。请在团队设置中的 “Service Keys” 下创建一个。

计费策略

响应格式取决于你团队的计费策略: 无论采用哪种计费策略,message_count 字段 (位于 consumption 内) 都会返回。

分组与粒度

使用 granularitygroup_by 控制返回数据的结构:
  • 无粒度或分组 — 在整个日期范围内返回一条聚合结果
  • granularity=daily — 每一行都包含一个格式为 YYYY-MM-DDtimestamp
  • granularity=monthly — 每一行都包含一个格式为 YYYY-MMtimestamp
  • group_by=user — 每一行都包含 user_iduser_email
  • group_by=user,model_uid — 每一行都包含 user_iduser_emailmodel_uid
  • group_by=ide — 每一行都包含一个 ide
  • group_by=ide,ide_version — 每一行都包含 ideide_version (按 ide_version 分组时,也必须同时包含 ide)
结果采用分页返回,默认每页 1,000 行 (最多 10,000 行) 。当有更多结果时, 响应会在 pagination 对象中包含一个 next_page_cursor。将其作为 page_cursor 查询 参数传入,以获取下一页。 页面游标会在 24 小时后过期。后续的分页请求不会作为新的查询计入你的速率限制。

缓存

响应包含一个 ETag 标头。为避免重复传输数据,请在请求中包含上一次返回的 ETag 值作为 If-None-Match 标头 ——如果数据未发生变化,服务器将返回 304 Not Modified

速率限制

此端点按团队实行速率限制:每小时 10 次请求。如果你超过此限制, 服务器会返回 429 Too Many Requests,并附带 Retry-After 标头。 对先前的查询结果进行分页 (即沿用 next_page_cursor) 不会计入此限制—— 只有每份报告的首次查询才会计入。较低的限制说明,此端点用于 定期生成报告,而非实时用量监控。

授权

Authorization
string
header
必填

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

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

请求头

If-None-Match
string

来自上一个响应的 ETag 值。如果数据未发生变化,服务器将返回 304 Not Modified

查询参数

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

按逗号分隔的结果分组维度列表。支持的维度:

  • user — 每行包含 user_iduser_email
  • model_uid — 每行包含 model_uid
  • ide — 每行包含 ide
  • ide_version — 每行包含 ide_version;还必须同时包含 ide
models
string

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

group_id
string

将结果筛选为特定组中的用户。服务密钥必须具有对此组的访问权限。

user_id
string

将结果筛选为特定用户(auth UID)。

page_size
integer
默认值:1000

每页返回的最大行数。

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

来自上一个响应中 pagination.next_page_cursor 的不透明游标,用于获取下一页。

响应

已成功返回用量数据。

data
object[]
必填

用量数据行数组。

pagination
object
必填
metadata
object
必填