ToAPIsToAPIs

查询令牌用量

查询名下所有 API Key 的逐请求 Token 消耗与费用

GET
/api/usage/tokens/requests

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

  • 查询名下所有 API Key 的逐请求 Token 消耗与费用，也可按单个 Key 过滤
  • 输入、输出、缓存命中 Token 分别统计
  • 汇总接口按 Key 聚合总量
  • 游标分页，时间窗口最长 31 天

这两个接口读取计费日志，返回每笔计费请求的 Token 明细与费用，以及按 Key 的汇总。与只能查询单个 Key 总额度的 查询令牌余额 接口互补。

认证方式

Authorizationstring请求头必填

本接口以用户账号身份认证，不使用 sk- API Key。

  1. 打开 账户设置页，在“系统访问令牌”卡片点击生成，得到访问令牌（不是 sk- key）。再次生成会使旧令牌失效。
  2. 请求时同时携带访问令牌和用户 ID：
Authorization: Bearer YOUR_ACCESS_TOKEN
X-User-Id: YOUR_USER_ID

数字形式的用户 ID 显示在同一设置页。

X-User-Idstring请求头必填

数字形式的用户 ID，必须与访问令牌一起提供。

接口地址

GET /api/usage/tokens/requests   # 逐请求明细
GET /api/usage/tokens/summary    # 按 Key 汇总

查询参数

两个接口参数相同。出现未定义或重复的参数会返回 422。

start_timestampinteger查询必填

时间窗口起点，Unix 秒时间戳（含该时刻）。

end_timestampinteger查询必填

时间窗口终点，Unix 秒时间戳（不含该时刻）。必须大于 start_timestamp，窗口最长 31 天。

token_idinteger查询

可选。按数字 ID 过滤为单个 API Key，不传则包含所有 Key。

page_sizeinteger查询默认值: 50

每页行数，1–100。

cursorstring查询

上一次响应中 meta.next_cursor 返回的分页游标。仅对生成它的同一接口、同一时间窗口和相同 token_id 过滤条件有效。

响应说明

GET /api/usage/tokens/requests 每笔计费请求返回一行，按时间倒序排列。

log_idinteger

请求对应的内部日志 ID，在响应内唯一。

created_atinteger

请求计费时间，Unix 秒时间戳。

token_idinteger

发起请求的 API Key ID。

token_namestring

API Key 名称。

model_namestring

实际服务的模型。

task_idstring

异步请求（图片/视频生成）的任务 ID；同步请求为空。

prompt_tokensinteger

计费的输入 Token 数。

completion_tokensinteger

计费的输出 Token 数。

cache_tokensinteger | null

命中的缓存输入 Token 数（缓存读取）。上游未上报时为 null。

cache_creation_tokensinteger | null

写入缓存的 Token 数，未上报时为 null。

reported_total_tokensinteger | null

上游服务商上报的总 Token 数（如有）。

total_tokensinteger

prompt_tokens + completion_tokens。

billing_phasestring

pre_consumed、settled，或对早期缺少计费元数据的日志返回 unknown。

quotainteger

消耗的额度，平台内部单位。

cost_usdstring

折算后的美元费用，计算方式 quota / quota_per_usd（见 meta）。以字符串返回以保持精度。

GET /api/usage/tokens/summary 每个 API Key 返回一行，按 token_id 升序。

token_idinteger

API Key ID。

request_countinteger

窗口内计费请求数。

prompt_tokensinteger

该 Key 的输入 Token 总量。

completion_tokensinteger

该 Key 的输出 Token 总量。

total_tokensinteger

prompt_tokens + completion_tokens。

quotainteger

该 Key 消耗的额度总量。

cost_usdstring

该 Key 的美元总费用。

Meta

meta.has_moreboolean

是否还有下一页。

meta.next_cursorstring

作为 cursor 参数传回即可获取下一页；has_more 为 false 时为空。

meta.quota_per_usdstring

cost_usd 折算使用的内部额度/美元比率。

meta.consume_logging_enabledboolean

消费日志开关是否开启；关闭时返回数据可能为空。

meta.refunds_includedboolean

当前恒为 false，退款金额不做扣减。

请求示例

curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/requests?start_timestamp=1759708800&end_timestamp=1760313600&page_size=100' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'
curl --request GET \
  --url 'https://toapis.com/api/usage/tokens/summary?start_timestamp=1759708800&end_timestamp=1760313600&token_id=45' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-User-Id: YOUR_USER_ID'
import requests

API_BASE = 'https://toapis.com'
headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'X-User-Id': 'YOUR_USER_ID',
}
params = {
    'start_timestamp': 1759708800,
    'end_timestamp': 1760313600,
    'page_size': 100,
}

while True:
    r = requests.get(f'{API_BASE}/api/usage/tokens/requests',
                     headers=headers, params=params)
    body = r.json()
    for row in body['data']:
        print(row['created_at'], row['token_name'], row['model_name'],
              row['prompt_tokens'], row['completion_tokens'],
              row['cache_tokens'], row['cost_usd'])
    if not body['meta']['has_more']:
        break
    params['cursor'] = body['meta']['next_cursor']

响应示例

{
  "success": true,
  "data": [
    {
      "log_id": 10241024,
      "created_at": 1760001234,
      "token_id": 45,
      "token_name": "prod-backend",
      "model_name": "gpt-5.1",
      "task_id": "",
      "prompt_tokens": 148320,
      "completion_tokens": 2198,
      "cache_tokens": 96000,
      "cache_creation_tokens": 0,
      "reported_total_tokens": 150518,
      "total_tokens": 150518,
      "billing_phase": "settled",
      "quota": 7839,
      "cost_usd": "0.015678"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 100,
    "has_more": true,
    "next_cursor": "eyJraW5kIjoicmVxdWVzdHMiLC4uLn0",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}
{
  "success": true,
  "data": [
    {
      "token_id": 45,
      "request_count": 87,
      "prompt_tokens": 3200400,
      "completion_tokens": 150220,
      "total_tokens": 3350620,
      "quota": 401234,
      "cost_usd": "0.802468"
    }
  ],
  "meta": {
    "start_timestamp": 1759708800,
    "end_timestamp": 1760313600,
    "page_size": 50,
    "has_more": false,
    "next_cursor": "",
    "cost_basis": "consume_log_quota",
    "currency": "USD",
    "quota_per_usd": "500000",
    "consume_logging_enabled": true,
    "refunds_included": false,
    "total_tokens_basis": "logged_prompt_plus_completion"
  }
}
{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "user authentication is required"
  }
}
{
  "success": false,
  "error": {
    "code": "invalid_query",
    "message": "time range must be positive and no longer than 31 days"
  }
}
{
  "success": false,
  "error": {
    "code": "query_timeout",
    "message": "usage query exceeded the time limit; use a shorter time range"
  }
}

注意事项

  • 仅列出已计费的请求。未计费的失败请求不会出现在结果中，响应中也不包含逐请求的成功标记。
  • 费用按计费时记录的额度折算，不按当前目录价重算，且不扣减退款。
  • 接口不会暴露原始 Key、渠道、IP 及请求/响应内容。
  • cursor 与接口、时间窗口、token_id 过滤条件绑定，不同查询之间不能复用。
  • 查询超时时间较短；如收到 query_timeout，请缩短时间窗口后重试。

查询令牌余额

查询当前 API Key 的剩余额度和已使用额度

查询用户余额

查询当前用户账户的剩余额度和已使用额度