查询用量明细 | ToAPIs Documentation

GET

/api/v1/account/usage/records

国内用户请注意: 中国大陆用户请使用 https://toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://toapis.com 请替换为 https://toapis.cn.

鉴权, 分页与错误处理见接入说明.

使用说明

用量区间最长 31 天. 明细按创建时间与 ID 倒序; 汇总按日期升序, 模型 UTF-8 字节序, 或 Key 的 null 桶后接数字 ID 升序. 每个汇总项只包含 day, model, api_key_id 中对应分组的一项. record_count 为日志行数, 不是完整请求次数. billing_phase 为 pre_consumed, settled 或 unknown, 不代表任务最终账务状态. 原请求追踪位于 trace, 不是本次查询的请求 ID. 可选追踪和上游 token 总量可能为 null, 不影响独立金额与输入输出 token. 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://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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, 不自行用输入和输出数量补齐.

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
        },
        "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"
    }
  }
}