按 Key 统计用量

GET /api/open/v1/usage/keys

请求参数

参数	位置	类型	必填	默认值	说明
start_timestamp	query	integer	否	见说明	起始时间（含），unix 秒
end_timestamp	query	integer	否	见说明	结束时间（含），unix 秒
group_by	query	string	否	key_name	分组方式：key_name 按请求发生时的 Key 名称聚合，同名 Key 合并为一行；key_id 每个 Key 一行
key_id	query	integer	否	—	按 Key ID 过滤，正整数；多值可重复参数或用逗号分隔。传其他用户的 ID 只会返回空
key_name	query	string	否	—	按请求发生时的 Key 名称精确过滤；多值需重复参数，不支持逗号分隔（名称本身可能含逗号）
p	query	integer	否	1	页码，取值 1–1000000
page_size	query	integer	否	10	每页条数，取值 1–1000
sort_by	query	string	否	total_tokens	排序字段：key_count（仅 group_by=key_name）、prompt_tokens、completion_tokens、total_tokens、amount
order	query	string	否	desc	排序方向：asc 或 desc

时间范围规则：

• 两端都省略：最近 30 天。
• 只传 start_timestamp：向后 30 天，且不超过当前时间。
• 只传 end_timestamp：向前 30 天。
• 范围最长 366 天。

多值参数每个最多 50 个值，超过返回 400 invalid_request。p / page_size 显式传入非法值返回 400，详见 分页。

请求示例

curl "https://www.routeapi.ai/api/open/v1/usage/keys?start_timestamp=1726400000&end_timestamp=1729000000&sort_by=total_tokens&order=desc&p=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_name": "bot",
        "key_count": 2,
        "prompt_tokens": 5000,
        "completion_tokens": 1000,
        "total_tokens": 6000,
        "amount": 0.20
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

group_by=key_id 时每个 Key 一行，带 key_id、不带 key_count：

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_id": 12,
        "key_name": "bot",
        "prompt_tokens": 3000,
        "completion_tokens": 600,
        "total_tokens": 3600,
        "amount": 0.12
      },
      {
        "key_id": 15,
        "key_name": "bot",
        "prompt_tokens": 2000,
        "completion_tokens": 400,
        "total_tokens": 2400,
        "amount": 0.08
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

响应字段

字段	类型	说明
items[].key_id	integer	仅 group_by=key_id。Key ID，可用于 获取 Key 等接口；0 表示不经 API Key 的用量（如操练场）
items[].key_name	string	group_by=key_name：请求发生时的 Key 名称。group_by=key_id：Key 的当前名称；Key 已不存在或 key_id 为 0 时，取该 Key 在时间范围内最近一次请求时的名称
items[].key_count	integer	仅 group_by=key_name。该名称下在时间范围内有消费的不同 Key 数量
items[].prompt_tokens	integer	该行的输入 token 总数
items[].completion_tokens	integer	该行的输出 token 总数
items[].total_tokens	integer	输入与输出 token 合计
items[].amount	number	该行消耗的金额（已扣除退款），站点币种，两位小数
total	integer	总行数：group_by=key_name 为名称数，group_by=key_id 为 Key 数（含 key_id 为 0 的行）
page	integer	当前页码
page_size	integer	实际生效的每页条数
start_timestamp	integer	实际生效的起始时间
end_timestamp	integer	实际生效的结束时间

错误

HTTP	code	场景
400	invalid_request	group_by、sort_by 或 order 取值非法、group_by=key_id 时 sort_by=key_count、key_id 不是正整数、时间戳非数字或为负数、时间范围非法、分页参数非法，或多值参数超过 50 个值
429	—	超过按用户的查询频率限制（默认 30 次/分钟），响应体可能为空

其他通用错误码见 开放平台 API 错误。

说明

• Key 名称可能重复：group_by=key_name 会把同名 Key 合并为一行，需要区分时用 group_by=key_id。不返回任何 Key 值。
• 先按 sort_by 指定的字段排序，取值相同时按 key_name（group_by=key_id 时按 key_id）升序，分页顺序稳定。
• 历史记录里保存的是请求发生时的 Key 名称，改名不会回溯改写。因此 group_by=key_name 下改名前后的用量分为两行；key_name 筛选也匹配请求时的名称，而 group_by=key_id 返回的是当前名称，两者可能不同。
• 各行 amount 之和等于 用量统计 的金额（不计四舍五入误差）。
• 只统计消费（计费）日志，失败请求不计入。
• token 数为原始计数，不是百万单位。
• 金额使用站点展示币种，见 查询余额。
• 每行 amount 独立四舍五入，各行相加与总量可能相差 ±0.01。
• 需要导出 Excel 时，请用相同筛选条件分页拉取本接口并汇总 items。
• 本接口与 用量统计、账户日志、导出日志、按模型统计 共享按用户的查询频率限制（默认 30 次/分钟），见 频率限制。