查询用量汇总
按天, 模型或 API Key 分组汇总用量
国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.
鉴权, 分页与错误处理见接入方式.
使用说明
按指定维度汇总用量, 用于按天, 按模型或按 Key 统计消费. group_by 决定分组方式: day 按日期升序, model 按模型名 UTF-8 字节序升序, api_key 先返回 null 分组再按数字 ID 升序; 每个汇总项只包含对应分组字段. from/to 每页必填, 区间最长 31 天.
record_count 是日志行数, unknown_phase_record_count 是无法确认账务阶段的行数, 两者都不等于完整请求数或最终净支出. group_by=model 或 api_key 时 meta.timezone=null.
meta 固定声明 records_mutable=true, refund_accounting=not_complete, consistency=eventual: 结算与退款会更新旧记录, 没有记录不代表零消费. 本接口与发票, 定价查询同属重量级查询: 在普通读取限流之外, 还有每用户每分钟 6 次的上限.
本接口与发票, 定价查询各有每用户每分钟 6 次的额外限制. 服务暂时不可用时返回 503.
鉴权
Authorizationstring请求头必填使用系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 模型 API Key 不能用于此接口, 无需 X-User-Id.
请求参数
fromstring查询必填带时区的 RFC 3339 起始时间, 包含该时刻. 与 to 成对提供.
约束: date-time.
tostring查询必填带时区的 RFC 3339 结束时间, 不包含该时刻, 必须晚于 from.
约束: date-time.
api_key_idstring查询自身模型 API Key 的十进制 ID 字符串. 不属于自己时返回 404, 已删除 Key 仍可用于查询自身历史用量.
约束: pattern=^[1-9][0-9]*$.
modelstring查询精确匹配模型标识. 用量接口中空字符串匹配空模型名.
约束: maxLength=255.
limitinteger查询默认值: 50每页最多返回的条目数.
约束: minimum=1; maximum=100; 默认值: 50.
cursorstring查询原样传入上一页的 next_cursor. 保留原筛选条件, 改变条件后重新开始.
约束: maxLength=2048.
group_bystring查询默认值: day按日期, 模型或 API Key 分组.
约束: day, model, api_key; 默认值: day.
timezonestring查询默认值: UTC仅 group_by=day 时可提供. 其他分组的响应 meta.timezone=null.
约束: UTC, Asia/Shanghai; 默认值: UTC.
请求示例
请求示例
curl --request GET \
--url 'https://api.toapis.com/api/v1/usage/summary?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&group_by=day&timezone=UTC' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'import requests
response = requests.get(
"https://api.toapis.com/api/v1/usage/summary",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
params={
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"group_by": "day",
"timezone": "UTC"
},
timeout=30,
)
response.raise_for_status()
print(response.json())const url = new URL("https://api.toapis.com/api/v1/usage/summary");
url.search = new URLSearchParams({
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"group_by": "day",
"timezone": "UTC"
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());响应字段
示例使用虚构数据. 金额样例假设 credits_per_usd="100", 实际换算以响应为准.
列表位于 data.items, 使用 has_more 和 next_cursor 翻页. 末页游标为 null, 不返回总数.
codeinteger业务状态码, 成功时为 0.
messagestring响应消息, 成功时为空字符串. 错误消息会按请求语言返回.
dataobject本次查询的结果对象.
data.itemsobject[]当前页的记录列表, 空结果为 [].
data.items[].daystring日期分组值, 仅 group_by=day 时返回, 日期由请求的 timezone 决定. 格式为 YYYY-MM-DD.
data.items[].modelstring模型分组值, 仅 group_by=model 时返回.
data.items[].api_key_idstring | nullAPI Key 分组值, 仅 group_by=api_key 时返回. 无 Key 的消费归入 null 分组.
data.items[].record_countinteger分组内消费日志的条数, 不保证等于完整请求次数.
data.items[].recorded_cost_usdstring分组内当前消费日志金额的 USD 合计, 不是完整退款核算后的净支出. 以十进制字符串返回以保持精度.
data.items[].recorded_creditsstring分组内当前消费日志记录的 credits 合计. 以十进制字符串返回以保持精度.
data.items[].input_tokensinteger分组内日志记录的输入 token 总量.
data.items[].output_tokensinteger分组内日志记录的输出 token 总量.
data.items[].unknown_phase_record_countinteger分组内无法确认账务阶段的日志条数.
data.has_moreboolean是否还有下一页.
data.next_cursorstring | null下一页游标, 原样作为 cursor 传入并保留筛选条件. 末页为 null.
data.metaobject数据来源, 查询范围和数据口径等元信息.
data.meta.scopestring查询的数据归属范围, 当前为认证账户自身. 固定值: "self".
data.meta.fromstring查询时间范围的下界, 包含该时刻. 时间格式为带时区的 RFC 3339.
data.meta.tostring查询时间范围的上界, 不包含该时刻. 时间格式为带时区的 RFC 3339.
data.meta.time_basisstring时间筛选和日期分组采用消费日志的创建时间. 固定值: "record_created_at".
data.meta.cost_basisstring金额采用当前消费日志行的值, 不是冻结的最终账单. 固定值: "current_consume_log_amount".
data.meta.refund_accountingstring退款核算的完整性. not_complete 表示不能作为完整净支出账本. 固定值: "not_complete".
data.meta.records_mutableboolean记录是否可能在结算或退款后更新. 当前为 true.
data.meta.consistencystring数据一致性类型. eventual 表示最终一致, 记录可能稍后更新. 固定值: "eventual".
data.meta.consume_logging_enabledboolean消费日志开关是否开启. 无记录不证明没有扣费.
data.meta.credits_per_usdstring每 1 USD 对应的 credits 数量. 使用此值进行换算. 以十进制字符串返回以保持精度.
data.meta.group_bystring本次汇总采用的分组维度.
data.meta.timezonestring | null日期分组的时区. 按模型或 API Key 分组时为 null.
响应示例
响应示例
{
"code": 0,
"message": "",
"data": {
"items": [
{
"day": "2026-11-01",
"record_count": 2,
"recorded_cost_usd": "0.04",
"recorded_credits": "4",
"input_tokens": 2000,
"output_tokens": 400,
"unknown_phase_record_count": 0
}
],
"has_more": false,
"next_cursor": null,
"meta": {
"scope": "self",
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"time_basis": "record_created_at",
"cost_basis": "current_consume_log_amount",
"refund_accounting": "not_complete",
"records_mutable": true,
"consistency": "eventual",
"consume_logging_enabled": true,
"credits_per_usd": "100",
"group_by": "day",
"timezone": "UTC"
}
}
}