查询用量汇总 | ToAPIs Documentation

GET

/api/v1/account/usage/summary

国内用户请注意: 中国大陆用户请使用 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.

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://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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 | null

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