按小时、UTC+8 自然日或自然月分页查询工作空间或 Agent 的用量趋势。
前提
已完成工作空间和 API Key 配置,接入方式见 API 总览与认证。时间格式、粒度选择和区间对齐规则见 Usage。
接口
POST /usage/trend
按小时、UTC+8 自然日或自然月查询用量变化。每个时间段返回总量、模型明细和工具明细,结果按时间升序分页。
请求体dimension 取值仅为小写 agent_id
agent_version 仅 time_range 查询时间范围 time_range.start_time 带时区的秒级 RFC 3339 开始时间;秒可以非零,无需对齐整分钟,不接受小数秒 time_range.end_time 结束时间,格式同上,必须晚于开始时间 granularity
page_size 每页最多返回的时间段数量,取值 page_token 首次查询不传。续页原样传入上一页的
| 请求示例查询当前工作空间的小时用量趋势,使用秒级起止时间。为演示分页,设置 查询 Agent 趋势时,将 |
响应字段request_id 请求标识 data.query_range 整次查询对齐后的实际区间,各页保持一致,不是当前页的起止范围 data.query_range.start_time 整次查询的开始时间,包含该时刻,使用 data.query_range.end_time 整次查询的结束时间,不包含该时刻,使用 data.data_updated_at 当前页返回用量记录中最近的已知更新时间,无记录或更新时间未知时为 data.granularity 实际使用的粒度: data.points 当前页的时间段列表,按 data.points[].start_time 当前时间段的开始时间,包含该时刻,使用 data.points[].end_time 当前时间段的结束时间,不包含该时刻,使用 data.points[].usage 当前时间段的用量,包含 data.has_more 是否还有下一页 data.next_page_token 下一页游标。 | 响应示例成功时返回 HTTP 200。上述请求实际统计 UTC+8 10:00—15:00。以下示例假设该区间仅 10:00—11:00 和 13:00—14:00 存在汇总统计记录;第一页返回第一个时间段: |
分页
将上一页返回的 next_page_token 原样传入 page_token。保持同一主账号、工作空间、维度、Agent、版本、原始起止时间、实际粒度及 page_size。起止时间按同一绝对时刻比较,等价时区写法可以互换;即使对齐后的 query_range 相同,也不能修改原始时间边界。
以下游标仅为格式示例,实际调用时请替换为上一页返回的值:
curl -X POST "$AGENTSTUDIO_URL/usage/trend" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dimension": "workspace",
"time_range": {
"start_time": "2026-11-02T10:15:30+08:00",
"end_time": "2026-11-02T14:00:01+08:00"
},
"granularity": "hour",
"page_size": 1,
"page_token": "v1_0123456789abcdef0123456789abcdef"
}'
本例下一页返回 13:00—14:00 的用量,has_more=false、next_page_token=null,分页结束。
- 每个游标自生成起有效期为 15 分钟,有效期内可重试;重试同一游标不会延长其有效期。游标失效返回 HTTP 410 /
page_token_expired,此时去掉page_token,重新查询第一页。 - 分页单位是完整时间段,
page_size只限制时间段数量。一个时间段内的模型和工具明细一起返回;本页全部时间段的模型与工具明细项合计最多 100,000,汇总total不计入该上限。 - 只返回有汇总统计记录的时间段,不自动填充缺失时间段。已有记录的指标即使为
0或null,该时间段仍会返回。 - 首次查询没有记录时,返回
points=[]、has_more=false、next_page_token=null,仍保留实际query_range和granularity。 - 分页期间统计数据可能继续更新,游标不锁定数据快照。续页从上一页最后一个时间段之后开始;后补到已翻过时间段的数据不会在后续页重复返回。需要刷新时从第一页重查,结果仍可能短暂命中缓存。
错误码见 Usage。