ToAPIsToAPIs
用量

查询用量汇总

按天, 模型或 API Key 分组汇总用量

GET
/api/v1/usage/summary

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