查询用量明细
按日志行分页查询当前账户的用量明细
国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.
鉴权, 分页与错误处理见接入方式.
使用说明
按消费日志分页返回用量明细, 用于对账或分析每次调用的花费. from/to 每页必填, 区间最长 31 天, 按创建时间与日志 ID 倒序. api_key_id 只能筛选自己名下 Key 的消费; 已删除的 Key 不影响历史记录查询, 没有关联 Key 的消费 api_key_id=null.
recorded_cost_usd/recorded_credits 是当前日志行的金额, 不保证等于最终净支出. billing_phase 取值为 pre_consumed, settled 或 unknown, 只表示日志行所处的账务阶段, 不代表任务最终账务状态. trace 是原生成请求的追踪信息, 与本次查询自身的请求 ID 无关.
meta 固定声明 records_mutable=true, refund_accounting=not_complete, consistency=eventual: 也就是说: 结算和退款会更新此前已返回的记录, 查不到记录不代表没有消费. 如果只把这些记录单向同步到自己的系统, 旧记录后续的修改不会被感知到.
鉴权
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.
请求示例
请求示例
curl --request GET \
--url 'https://api.toapis.com/api/v1/usage/records?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&api_key_id=42&limit=20' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'import requests
response = requests.get(
"https://api.toapis.com/api/v1/usage/records",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
params={
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"api_key_id": "42",
"limit": "20"
},
timeout=30,
)
response.raise_for_status()
print(response.json())const url = new URL("https://api.toapis.com/api/v1/usage/records");
url.search = new URLSearchParams({
"from": "2026-11-01T00:00:00Z",
"to": "2026-11-02T00:00:00Z",
"api_key_id": "42",
"limit": "20"
}).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[].idstring消费日志记录的 ID. 以十进制 ID 字符串返回.
data.items[].created_atstring | null创建时间. 时间格式为带时区的 RFC 3339. 无法确认或不适用时为 null.
data.items[].api_key_idstring | null关联模型 API Key 的 ID. 没有关联 Key 时为 null.
data.items[].key_namestring | null日志中记录的 API Key 名称. 无法确认或不适用时为 null.
data.items[].modelstring模型标识.
data.items[].task_idstring | null关联的平台任务 ID. 无法确认或不适用时为 null.
data.items[].recorded_cost_usdstring当前消费日志记录的 USD 金额, 不代表完整退款核算后的净支出. 以十进制字符串返回以保持精度.
data.items[].recorded_creditsstring当前消费日志记录的消费额度, 单位为 credits. 以十进制字符串返回以保持精度.
data.items[].billing_phasestring日志记录的账务阶段, 不等同于任务最终账务状态. 可选值: pre_consumed, settled, unknown.
data.items[].usageobject日志记录的输入, 输出及上游报告的 token 数量.
data.items[].usage.input_tokensinteger日志记录的输入 token 数量.
data.items[].usage.output_tokensinteger日志记录的输出 token 数量.
data.items[].usage.reported_total_tokensinteger | null上游报告的总 token 数量, 无法确认时为 null, 不自行用输入和输出数量补齐.
四个缓存字段始终返回: 未记录, 无效或超出读取预算时为 null, 明确记录的零值为 0. 拆分值和总量互不推算. 日志为零也不代表上游明确上报了零. input_tokens 保留日志原始口径, 不保证包含缓存量, 不要用缓存读取量除以输入量计算命中率. 汇总接口暂不提供缓存字段聚合.
data.items[].usage.cache_read_tokensinteger | null日志记录的缓存读取 token 数量.
data.items[].usage.cache_write_tokensinteger | null日志记录的缓存写入总量, 包含 5m 和 1h 拆分, 不与拆分重复相加.
data.items[].usage.cache_write_5m_tokensinteger | null日志明确记录的 5 分钟缓存写入量.
data.items[].usage.cache_write_1h_tokensinteger | null日志明确记录的 1 小时缓存写入量.
data.items[].traceobject | null原生成请求的追踪信息, 与本次查询的请求 ID 不同. 无法确认或不适用时为 null.
data.items[].trace.request_idstring | null原生成请求的平台追踪 ID. 无法确认或不适用时为 null.
data.items[].trace.client_request_idstring | null原生成请求中记录的客户侧请求 ID. 无法确认或不适用时为 null.
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 数量. 使用此值进行换算. 以十进制字符串返回以保持精度.
响应示例
响应示例
{
"code": 0,
"message": "",
"data": {
"items": [
{
"id": "9001",
"created_at": "2026-11-01T08:00:00Z",
"api_key_id": "42",
"key_name": "Example Key",
"model": "example-text-model",
"task_id": null,
"recorded_cost_usd": "0.02",
"recorded_credits": "2",
"billing_phase": "settled",
"usage": {
"input_tokens": 1000,
"output_tokens": 200,
"reported_total_tokens": 1200,
"cache_read_tokens": 300,
"cache_write_tokens": 200,
"cache_write_5m_tokens": 150,
"cache_write_1h_tokens": 50
},
"trace": {
"request_id": "request_example_01",
"client_request_id": "client_example_01"
}
}
],
"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"
}
}
}