curl --request POST \
--url 'https://maas.qianwenaiapi.com/api/v1/agentstudio/usage/trend' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '
{
"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
}
'{
"request_id": "req_trend_example",
"data": {
"query_range": {
"start_time": "2026-11-02T10:00:00+08:00",
"end_time": "2026-11-02T15:00:00+08:00"
},
"data_updated_at": "2026-11-02T11:05:00+08:00",
"granularity": "hour",
"points": [
{
"start_time": "2026-11-02T10:00:00+08:00",
"end_time": "2026-11-02T11:00:00+08:00",
"usage": {
"total": {
"input_tokens": {
"value": 600,
"unit": "tokens"
},
"output_tokens": {
"value": 120,
"unit": "tokens"
},
"total_tokens": {
"value": 720,
"unit": "tokens"
},
"cache_read_tokens": {
"value": 240,
"unit": "tokens"
},
"cache_creation_tokens": {
"value": 60,
"unit": "tokens"
},
"cache_hit_ratio": {
"value": 0.4,
"unit": "ratio"
},
"model_call_count": {
"value": 3,
"unit": "count"
},
"tool_call_count": {
"value": 2,
"unit": "count"
},
"builtin_tool_call_count": {
"value": 0,
"unit": "count"
},
"mcp_tool_call_count": {
"value": 2,
"unit": "count"
},
"custom_tool_call_count": {
"value": 0,
"unit": "count"
},
"turns": {
"value": 1,
"unit": "count"
},
"steps": {
"value": 5,
"unit": "count"
},
"interrupt_error_count": {
"value": 0,
"unit": "count"
},
"model_failed_count": {
"value": 1,
"unit": "count"
},
"tool_failed_count": {
"value": 1,
"unit": "count"
},
"runtime_ms": {
"value": 36000,
"unit": "ms"
}
},
"models": [
{
"model_name": "qwen-plus",
"usage": {
"input_tokens": {
"value": 600,
"unit": "tokens"
},
"output_tokens": {
"value": 120,
"unit": "tokens"
},
"total_tokens": {
"value": 720,
"unit": "tokens"
},
"cache_read_tokens": {
"value": 240,
"unit": "tokens"
},
"cache_creation_tokens": {
"value": 60,
"unit": "tokens"
},
"cache_hit_ratio": {
"value": 0.4,
"unit": "ratio"
},
"call_count": {
"value": 3,
"unit": "count"
},
"failed_count": {
"value": 1,
"unit": "count"
}
}
}
],
"tools": [
{
"source": "mcp",
"tool_name": "web_search",
"usage": {
"call_count": {
"value": 2,
"unit": "count"
},
"failed_count": {
"value": 1,
"unit": "count"
}
}
}
]
}
}
],
"has_more": true,
"next_page_token": "v1_0123456789abcdef0123456789abcdef"
}
}查询维度
dimension 仅支持小写 workspace、agent,不支持 session。workspace 维度不传 Agent 筛选参数,传入时返回 HTTP 400 / invalid_parameter;agent 维度的 agent_id 必须为非空单值。时间格式、粒度选择和区间对齐规则见 查询用量汇总。
分页
将上一页返回的next_page_token 原样传入 page_token。保持同一主账号、工作空间、维度、Agent、版本、原始起止时间、实际粒度及 page_size。起止时间按同一绝对时刻比较,等价时区写法可以互换;即使对齐后的 query_range 相同,也不能修改原始时间边界。
- 每个游标自生成起有效期为 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。 - 分页期间统计数据可能继续更新,游标不锁定数据快照。续页从上一页最后一个时间段之后开始;后补到已翻过时间段的数据不会在后续页重复返回。需要刷新时从第一页重查,结果仍可能短暂命中缓存。
data.query_range 是整次查询对齐后的实际区间,各页保持一致,不是当前页的起止范围。data_updated_at 表示当前页返回用量记录中最近的已知更新时间,不同页的值可能不同。用量对象结构和空结果规则见 查询用量汇总,错误码见查询用量汇总。鉴权
DashScope API Key
请求体
application/json取值仅为小写 workspace、agent,区分大小写。不支持 session
dimension=agent 时必填,指定一个 Agent;workspace 维度不传。必须为非空单值
仅 dimension=agent 可用。不传或为 null 时合并全部版本;不能是空字符串或纯空白,按原始字符串精确匹配,不自动去除首尾空格
hour、day 或 month;不传时自动选择,不接受显式 null
每页最多返回的时间段数量,取值 1~100,默认 100;不接受显式 null
首次查询不传。续页原样传入上一页的 next_page_token,不解析或自行拼接;不接受显式 null、空字符串、纯空白或无效游标。游标自生成起有效期为 15 分钟,失效后返回 HTTP 410 / page_token_expired
响应
请求标识
显示子属性
显示子属性
当前页返回用量记录中最近的已知更新时间,无记录或更新时间未知时为 null。不同页的值可能不同
实际使用的粒度
当前页的时间段列表,按 start_time 升序;无记录时为 []
显示子属性
显示子属性
当前时间段的开始时间,包含该时刻,使用 +08:00 时区
当前时间段的结束时间,不包含该时刻,使用 +08:00 时区
当前时间段的用量,包含 total、models、tools。total、models、tools 是同一范围的不同统计视图,不应将总量与明细重复相加
显示子属性
显示子属性
当前时间段的汇总指标
显示子属性
显示子属性
按模型名称分组的用量明细,无明细时为 []
显示子属性
显示子属性
模型名称
当前模型的用量指标
显示子属性
显示子属性
按工具来源和名称分组的用量明细,无明细时为 []
显示子属性
显示子属性
工具来源:builtin(内置工具)、mcp(MCP 工具)、custom(自定义工具);未知时为 null
工具名称
当前工具的用量指标。工具明细不包含 Token 或运行时长指标
显示子属性
显示子属性
是否还有下一页
下一页游标。has_more=true 时为非空字符串;末页为 null