跳转到主要内容
Usage

查询用量趋势

按小时、UTC+8 自然日或自然月分页查询工作空间或 Agent 的用量趋势。

POST
/api/v1/agentstudio/usage/trend
cURL
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 表示当前页返回用量记录中最近的已知更新时间,不同页的值可能不同。用量对象结构和空结果规则见 查询用量汇总,错误码见查询用量汇总。

鉴权

string
header
必填

DashScope API Key

请求体

application/json
enum<string>
必填

取值仅为小写 workspace、agent,区分大小写。不支持 session

workspace,agent
object
必填

查询时间范围。时间范围按 UTC+8 对齐

string

dimension=agent 时必填,指定一个 Agent;workspace 维度不传。必须为非空单值

string | null

仅 dimension=agent 可用。不传或为 null 时合并全部版本;不能是空字符串或纯空白,按原始字符串精确匹配,不自动去除首尾空格

enum<string>

hour、day 或 month;不传时自动选择,不接受显式 null

hour,day,month
integer
默认值100

每页最多返回的时间段数量,取值 1~100,默认 100;不接受显式 null

1 <= x <= 100
string

首次查询不传。续页原样传入上一页的 next_page_token,不解析或自行拼接;不接受显式 null、空字符串、纯空白或无效游标。游标自生成起有效期为 15 分钟,失效后返回 HTTP 410 / page_token_expired

响应

200-application/json
string

请求标识

object