> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询令牌用量

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

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

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

这两个接口读取计费日志，返回每笔计费请求的 Token 明细与费用，以及按 Key 的汇总。与只能查询单个 Key 总额度的 [查询令牌余额](/docs/cn/api-reference/account/token-balance) 接口互补。

## 认证方式

<ParamField header="Authorization" type="string" required>
  本接口以**用户账号**身份认证，不使用 `sk-` API Key。

  1. 打开 [账户设置页](https://toapis.com/dashboard/settings)，在“系统访问令牌”卡片点击生成，得到访问令牌（不是 `sk-` key）。再次生成会使旧令牌失效。
  2. 请求时同时携带访问令牌和用户 ID：

  ```
  Authorization: Bearer YOUR_ACCESS_TOKEN
  X-User-Id: YOUR_USER_ID
  ```

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

<ParamField header="X-User-Id" type="string" required>
  数字形式的用户 ID，必须与访问令牌一起提供。
</ParamField>

## 接口地址

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

## 查询参数

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

<ParamField query="start_timestamp" type="integer" required>
  时间窗口起点，Unix 秒时间戳（含该时刻）。
</ParamField>

<ParamField query="end_timestamp" type="integer" required>
  时间窗口终点，Unix 秒时间戳（不含该时刻）。必须大于 `start_timestamp`，窗口最长 31 天。
</ParamField>

<ParamField query="token_id" type="integer">
  可选。按数字 ID 过滤为单个 API Key，不传则包含所有 Key。
</ParamField>

<ParamField query="page_size" type="integer" default="50">
  每页行数，`1`–`100`。
</ParamField>

<ParamField query="cursor" type="string">
  上一次响应中 `meta.next_cursor` 返回的分页游标。仅对生成它的同一接口、同一时间窗口和相同 `token_id` 过滤条件有效。
</ParamField>

## 响应说明

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

<ResponseField name="log_id" type="integer">
  请求对应的内部日志 ID，在响应内唯一。
</ResponseField>

<ResponseField name="created_at" type="integer">
  请求计费时间，Unix 秒时间戳。
</ResponseField>

<ResponseField name="token_id" type="integer">
  发起请求的 API Key ID。
</ResponseField>

<ResponseField name="token_name" type="string">
  API Key 名称。
</ResponseField>

<ResponseField name="model_name" type="string">
  实际服务的模型。
</ResponseField>

<ResponseField name="task_id" type="string">
  异步请求（图片/视频生成）的任务 ID；同步请求为空。
</ResponseField>

<ResponseField name="prompt_tokens" type="integer">
  计费的输入 Token 数。
</ResponseField>

<ResponseField name="completion_tokens" type="integer">
  计费的输出 Token 数。
</ResponseField>

<ResponseField name="cache_tokens" type="integer | null">
  命中的缓存输入 Token 数（缓存读取）。上游未上报时为 `null`。
</ResponseField>

<ResponseField name="cache_creation_tokens" type="integer | null">
  写入缓存的 Token 数，未上报时为 `null`。
</ResponseField>

<ResponseField name="reported_total_tokens" type="integer | null">
  上游服务商上报的总 Token 数（如有）。
</ResponseField>

<ResponseField name="total_tokens" type="integer">
  `prompt_tokens + completion_tokens`。
</ResponseField>

<ResponseField name="billing_phase" type="string">
  `pre_consumed`、`settled`，或对早期缺少计费元数据的日志返回 `unknown`。
</ResponseField>

<ResponseField name="quota" type="integer">
  消耗的额度，平台内部单位。
</ResponseField>

<ResponseField name="cost_usd" type="string">
  折算后的美元费用，计算方式 `quota / quota_per_usd`（见 `meta`）。以字符串返回以保持精度。
</ResponseField>

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

<ResponseField name="token_id" type="integer">
  API Key ID。
</ResponseField>

<ResponseField name="request_count" type="integer">
  窗口内计费请求数。
</ResponseField>

<ResponseField name="prompt_tokens" type="integer">
  该 Key 的输入 Token 总量。
</ResponseField>

<ResponseField name="completion_tokens" type="integer">
  该 Key 的输出 Token 总量。
</ResponseField>

<ResponseField name="total_tokens" type="integer">
  `prompt_tokens + completion_tokens`。
</ResponseField>

<ResponseField name="quota" type="integer">
  该 Key 消耗的额度总量。
</ResponseField>

<ResponseField name="cost_usd" type="string">
  该 Key 的美元总费用。
</ResponseField>

### Meta

<ResponseField name="meta.has_more" type="boolean">
  是否还有下一页。
</ResponseField>

<ResponseField name="meta.next_cursor" type="string">
  作为 `cursor` 参数传回即可获取下一页；`has_more` 为 `false` 时为空。
</ResponseField>

<ResponseField name="meta.quota_per_usd" type="string">
  `cost_usd` 折算使用的内部额度/美元比率。
</ResponseField>

<ResponseField name="meta.consume_logging_enabled" type="boolean">
  消费日志开关是否开启；关闭时返回数据可能为空。
</ResponseField>

<ResponseField name="meta.refunds_included" type="boolean">
  当前恒为 `false`，退款金额不做扣减。
</ResponseField>

<RequestExample>
  ```bash cURL — 逐请求明细 theme={null}
  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'
  ```

  ```bash cURL — 按 Key 汇总 theme={null}
  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'
  ```

  ```python Python — 遍历全部页 theme={null}
  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']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - requests theme={null}
  {
    "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"
    }
  }
  ```

  ```json 200 - summary theme={null}
  {
    "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"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": {
      "code": "unauthorized",
      "message": "user authentication is required"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "success": false,
    "error": {
      "code": "invalid_query",
      "message": "time range must be positive and no longer than 31 days"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "success": false,
    "error": {
      "code": "query_timeout",
      "message": "usage query exceeded the time limit; use a shorter time range"
    }
  }
  ```
</ResponseExample>

## 注意事项

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.