跳转到主要内容
Usage

查询用量汇总

查询工作空间、Agent 或 Session 的用量汇总及模型、工具明细。

POST
/api/v1/agentstudio/usage/summary
cURL
curl --request POST \
  --url 'https://maas.qianwenaiapi.com/api/v1/agentstudio/usage/summary' \
  --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"
}
'
{
  "request_id": "req_summary_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-02T14:10:00+08:00",
    "usage": {
      "total": {
        "input_tokens": {
          "value": 1000,
          "unit": "tokens"
        },
        "output_tokens": {
          "value": 200,
          "unit": "tokens"
        },
        "total_tokens": {
          "value": 1200,
          "unit": "tokens"
        },
        "cache_read_tokens": {
          "value": 400,
          "unit": "tokens"
        },
        "cache_creation_tokens": {
          "value": 100,
          "unit": "tokens"
        },
        "cache_hit_ratio": {
          "value": 0.4,
          "unit": "ratio"
        },
        "model_call_count": {
          "value": 5,
          "unit": "count"
        },
        "tool_call_count": {
          "value": 3,
          "unit": "count"
        },
        "builtin_tool_call_count": {
          "value": 0,
          "unit": "count"
        },
        "mcp_tool_call_count": {
          "value": 3,
          "unit": "count"
        },
        "custom_tool_call_count": {
          "value": 0,
          "unit": "count"
        },
        "turns": {
          "value": 2,
          "unit": "count"
        },
        "steps": {
          "value": 8,
          "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": 60000,
          "unit": "ms"
        }
      },
      "models": [
        {
          "model_name": "qwen-plus",
          "usage": {
            "input_tokens": {
              "value": 1000,
              "unit": "tokens"
            },
            "output_tokens": {
              "value": 200,
              "unit": "tokens"
            },
            "total_tokens": {
              "value": 1200,
              "unit": "tokens"
            },
            "cache_read_tokens": {
              "value": 400,
              "unit": "tokens"
            },
            "cache_creation_tokens": {
              "value": 100,
              "unit": "tokens"
            },
            "cache_hit_ratio": {
              "value": 0.4,
              "unit": "ratio"
            },
            "call_count": {
              "value": 5,
              "unit": "count"
            },
            "failed_count": {
              "value": 1,
              "unit": "count"
            }
          }
        }
      ],
      "tools": [
        {
          "source": "mcp",
          "tool_name": "web_search",
          "usage": {
            "call_count": {
              "value": 3,
              "unit": "count"
            },
            "failed_count": {
              "value": 1,
              "unit": "count"
            }
          }
        }
      ]
    }
  }
}

查询维度

dimension查询范围参数要求
workspace当前工作空间的用量必传 time_range,不传 agent_id、agent_version、session_id
agent当前工作空间内指定 Agent 的用量必传 agent_id、time_range,可传 agent_version,不传 session_id
session当前工作空间内指定 Session 的生命周期累计用量只传 dimension、session_id;不传 Agent 筛选、time_range 或 granularity
agent_id、session_id 必须为非空单值。time_range、granularity 不接受显式 null。workspace 维度传入 Agent 筛选,或 session 维度传入 time_range、granularity,返回 HTTP 400 / invalid_parameter。时间格式、粒度选择和区间对齐规则见时间范围与粒度。 Session 查询返回相同的 usage 结构,不包含 query_range 或 Session 标题、状态等元数据。服务先校验 Session 归属,再查询生命周期累计用量。Session 存在但尚无统计记录时,指标 value 为 null,模型和工具明细为空数组;不会据此返回 Session 不存在。 此接口一次返回总量及全部模型、工具明细,不提供分页参数;单次模型与工具明细项合计上限为 100,000,超出返回 HTTP 400 / query_limit_exceeded。用量对象结构和空结果规则见用量对象。

时间范围与粒度

本节适用于工作空间和 Agent 的汇总与趋势查询。Session 汇总固定查询生命周期累计用量,不使用时间范围和粒度。

时间格式

起止时间使用带时区的秒级 RFC 3339 字符串,支持 Z 或数字时区偏移。秒可以非零,无需对齐整分钟,例如:
  • 2026-11-02T10:00:30+08:00
  • 2026-11-02T02:00:30Z,与上一项表示同一时刻。
不接受 Unix 时间戳、缺少时区的字符串或小数秒,例如 2026-11-02T10:00:00.123+08:00。响应时间统一使用 +08:00;运行时长使用毫秒数。

自动选择粒度

省略 granularity 时,按原始请求区间选择粒度:
原始区间使用粒度
不超过 72 小时hour
超过 72 小时,且终点不晚于起点在 UTC+8 下加 3 个日历月day
其他情况month
显式传入 granularity 时使用指定粒度,支持 hour、day、month。

实际统计区间

服务按 UTC+8(Asia/Shanghai)将开始时间向前、结束时间向后对齐到完整时间段,实际区间由响应的 query_range 给出。
粒度对齐边界
hour每小时整点
dayUTC+8 每日 00:00
monthUTC+8 每月 1 日 00:00,自然月长度随月份变化
例如,指定 hour 查询 UTC+8 10:15:30—14:00:01,实际统计 10:00:00—15:00:00。结束时间已在边界上时不再扩展,例如 10:00:00—14:00:00 保持不变。 区间均为左闭右开,即包含开始时刻、不包含结束时刻。比较汇总与趋势时,使用相同的查询条件,并核对 query_range。比例指标需合计分子、分母后重新计算,不能直接相加或平均。

用量对象

汇总响应的 data.usage 与趋势响应的 data.points[].usage 使用相同结构:
字段类型说明
totalobject当前范围的汇总指标
modelsarray模型明细,按 model_name 分组
toolsarray工具明细,按 source、tool_name 分组;同名但来源不同的工具分别返回

指标值与单位

每个指标包含 value、unit 两个字段:
{
  "input_tokens": {"value": 1000, "unit": "tokens"},
  "tool_call_count": {"value": 3, "unit": "count"},
  "runtime_ms": {"value": 60000, "unit": "ms"},
  "cache_hit_ratio": {"value": 0.4, "unit": "ratio"}
}
unitvalue 类型含义
tokensint64 / nullToken 数量
countint64 / null次数
msint64 / null毫秒
rationumber / null小数比例,例如 0.4 表示 40%
指标未知时保留对象和单位,例如 {"value":null,"unit":"tokens"};已知零用量返回 0。不要将 null 当作零。

汇总指标(total)

字段单位说明
input_tokenstokens模型输入 Token 数
output_tokenstokens模型输出 Token 数
total_tokenstokens输入与输出 Token 之和;任一项未知时为 null
cache_read_tokenstokens从缓存读取的输入 Token 数
cache_creation_tokenstokens创建缓存的输入 Token 数
cache_hit_ratioratiocache_read_tokens / input_tokens。输入为 0、输入未知或缓存读取量未知时为 null;结果保留 8 位小数,四舍五入
model_call_countcount模型调用次数,按已记录的模型请求结束事件统计,包含成功和失败调用
tool_call_countcount工具调用次数,按调用开始统计,包含成功、失败和尚未结束的调用
builtin_tool_call_countcount内置工具调用次数
mcp_tool_call_countcountMCP 工具调用次数
custom_tool_call_countcount自定义工具调用次数
turnscount交互轮数,按 role=user 的事件计数
stepscount执行步骤数,每次模型请求结束、每次工具调用开始各计一步
interrupt_error_countcount非模型、工具调用类的错误事件数;模型和工具调用失败分别计入对应失败数
model_failed_countcount模型调用失败次数
tool_failed_countcount已确认的工具调用失败次数
runtime_msms已结算运行片段的累计时长,尚未结算的运行片段暂不计入
缓存读取和缓存创建 Token 已属于输入用量,计算 total_tokens 时不要再次叠加。total、models、tools 是同一范围的不同统计视图,不应将总量与明细重复相加。

模型明细(models)

字段类型说明
models[].model_namestring / null模型名称
models[].usageobject当前模型的用量指标
models[].usage 包含以下指标:
字段单位说明
input_tokens、output_tokens、total_tokenstokens当前模型的输入、输出、总 Token 数,计算规则与汇总相同
cache_read_tokens、cache_creation_tokenstokens当前模型的缓存读取、缓存创建 Token 数
cache_hit_ratioratio当前模型的缓存命中率,计算规则与汇总相同
call_countcount当前模型的调用次数
failed_countcount当前模型的调用失败次数

工具明细(tools)

字段类型说明
tools[].sourcestring / null工具来源:builtin(内置工具)、mcp(MCP 工具)、custom(自定义工具);未知时为 null
tools[].tool_namestring / null工具名称
tools[].usage.call_countobject调用次数,unit=count
tools[].usage.failed_countobject已确认的调用失败次数,unit=count
工具明细不包含 Token 或运行时长指标。汇总接口不保证模型、工具明细数组的返回顺序;趋势接口的 points 按时间段升序返回。模型名称、工具名称或来源未知时,保留对应明细,相关字段可为 null。

数据更新与空结果

  • 统计结果会随用量处理持续更新,最近发生的调用可能尚未出现在结果中。结果可能短暂命中缓存,连续请求不保证立即反映最新统计。
  • data_updated_at 表示本次结果中最近的已知来源更新时间,不表示该时刻之前的数据已经全部统计完成,也不是本次请求时间。
  • 汇总没有匹配统计记录时,保留 usage.total 及各指标单位,指标 value 为 null,models、tools 为 [],data_updated_at 为 null。工作空间、Agent 维度仍返回 query_range。
  • 趋势没有匹配统计记录时返回空 points。缺失时间段不会自动补零。

错误码

HTTP 状态码错误码说明及处理方式
400invalid_parameter参数不合法,包括不支持的维度、粒度、时间格式、分页大小或请求体格式错误;根据 error.message 修正请求
400invalid_page_token分页游标格式错误,或续页身份、原始查询条件、实际粒度、page_size 与游标不匹配;使用上页返回的游标并保持查询条件一致。仅趋势查询
400query_limit_exceeded模型与工具明细项合计超过 100,000:汇总按整个查询范围计算,趋势按当前页计算。汇总可缩小时间范围或查询更具体的维度,趋势可减小 page_size 或改用更细粒度
404not_foundSession 不存在或不属于当前账号和工作空间,仅适用于 Session 汇总查询
410page_token_expired分页游标已失效,移除 page_token 后从第一页重查。仅趋势查询
429rate_limit两个用量接口共用主账号和工作空间维度的频率限制;降低并发并稍后重试
503service_unavailable用量查询或分页服务暂不可用,稍后重试
500internal_error服务内部异常,保留 request_id 以便排查

鉴权

string
header
必填

DashScope API Key

请求体

application/json
enum<string>
必填

查询维度,区分大小写。取值仅为 workspace、agent、session

workspace,agent,session
string

dimension=agent 时必填,指定一个 Agent;其他维度不传

string | null

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

string

dimension=session 时必填。使用创建 Session 时返回的 ID;必须为非空、非纯空白的单个字符串,其他维度不传

object

workspace、agent 维度必填;session 维度不接受。时间范围按 UTC+8 对齐

enum<string>

workspace、agent 维度可用;不传时自动选择。影响实际统计区间的对齐方式。session 维度不传。不接受显式 null

hour,day,month

响应

200-application/json
string

请求标识,可用于问题排查

object

用量查询结果