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

# 日志与账单查询

> 按请求 ID 查询当前 API Key 所属用户的日志、Token 用量、账单金额和资金来源。

`GET /api/usage` 按 `request_id` 精确查询当前 API Key 所属用户的日志和账单。一次查询可能返回多条记录，不保证请求 ID 唯一。

<Info>
  本文依据 2026-10-13 的接口契约整理，实际业务日志查询结果尚未验证。海外查询节点为 `https://reqs.anyfast.ai`。
</Info>

## 快速调用

```bash cURL theme={null}
export SERVICE_BASE_URL='https://reqs.anyfast.ai'
export ANYFAST_API_KEY='sk-YOUR_API_KEY'

curl --get "${SERVICE_BASE_URL}/api/usage" \
  -H "Authorization: Bearer ${ANYFAST_API_KEY}" \
  -H 'Accept-Language: zh-CN' \
  --data-urlencode 'request_id=req-001' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'offset=0'
```

使用 URL 查询参数，无需请求体。路径必须为 `/api/usage`；`/api/usage/` 返回 `404`。

## 身份认证

| 请求头 | 必填 | 说明 |
| - | - | - |
| `Authorization` | 是 | `Bearer sk-YOUR_API_KEY`，只允许一个 Authorization 请求头。 |
| `Accept-Language` | 否 | 控制提示信息和资金来源标签的语言，默认简体中文。 |

`Bearer` 大小写不敏感。API Key 必须以小写 `sk-` 开头，前缀后不能为空，且不能包含空白。不带前缀、使用 `SK-`、仅提供 `sk-`、重复请求头或令牌无效，均返回 `401`。

鉴权通过后才校验查询参数。无效令牌搭配错误参数时，优先返回 `401`。

查询始终限定 API Key 所属用户。不能通过 `user_id` 参数、`X-User-ID` 或其他请求头选择其他用户；显式传入 `user_id` 返回 `400`。其他用户即使拥有相同请求 ID，也不会返回其账单。

## 查询参数

| 参数 | 类型 | 必填 | 默认值 | 约束 |
| - | - | - | - | - |
| `request_id` | string | 是 | 无 | 精确匹配，不能为空或纯空白；无需 `sk-` 前缀，无应用层 256 字节长度限制。 |
| `limit` | integer | 否 | `100` | 每页条数，范围 `1–1000`，含边界。 |
| `offset` | integer | 否 | `0` | 跳过条数，范围 `0–1000000`，含边界。 |

参数名区分大小写。非空 `request_id` 保留原始首尾空格参与精确匹配。

以下情况返回 `400`：缺少或传入空白 `request_id`；未知参数；同名参数重复；显式空值；整数格式或范围错误；查询字符串编码错误。接口不支持时间范围、模型名称、自定义排序、`page` 或 `user_id` 参数。

## 分页与排序

第一页使用 `offset=0`，后续按本页实际返回条数增加 offset。响应只包含本页数组，没有 `total`、`has_more` 或游标。

返回数量小于 `limit` 时，本次查询已到末页；恰好等于 `limit` 时，下一页可能为空。当前页为空统一返回 `202`，包括 offset 超出已有记录的情况。

<Warning>
  `202` 仅表示本次查询无结果，不能据此判断账单生成进度。持续写入或更新期间，offset 分页可能重复或遗漏记录，不提供快照一致性。
</Warning>

记录先按创建时间降序，再按请求 ID 升序、输入 Token 降序、输出 Token 降序、模型名称升序、quota 降序、af\_usage 升序和 other 升序排列；后三项空值置后。数据不变时返回内容稳定；完全相同的记录不会去重。

## 成功响应

HTTP `200`。以下数据为示例：

```json theme={null}
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "request_id": "req-001",
      "prompt_tokens": 100,
      "completion_tokens": 200,
      "total_tokens": 300,
      "mode_name": "example-model",
      "request_time": "[24/Sep/2026:10:15:32 +0800]",
      "cache_read_tokens": 20,
      "cache_write_tokens": 10,
      "cache_write_5m_tokens": 10,
      "cache_write_1h_tokens": 0,
      "spend": "0.200002",
      "original_price": "0.500006",
      "discount_rate": "0.4000",
      "funding_source": "钱包: USD 0.200002",
      "currency": "USD"
    }
  ]
}
```

所有业务 JSON 响应包含 `code`（与 HTTP 状态码相同）、`msg`（本地化提示）和 `data`（数组）。无结果或失败时 `data` 为 `[]`，不会为 `null`。调用方应按状态码或 `code` 分支处理，不应依赖提示文本。

## 日志字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `request_id` | string | 请求标识。 |
| `prompt_tokens` | integer (int64) | 输入 Token 数；存储值为空时返回 `0`。 |
| `completion_tokens` | integer (int64) | 输出 Token 数；存储值为空时返回 `0`。 |
| `total_tokens` | integer (int64) | 每条记录的 `prompt_tokens + completion_tokens`。 |
| `mode_name` | string | 模型名称。响应字段确为 `mode_name`，不是 `model_name`。 |
| `request_time` | string | 固定 UTC+8，含方括号和英文月份缩写，例如 `[24/Sep/2026:10:15:32 +0800]`。不随语言或服务器时区变化。 |
| `cache_read_tokens` | integer (int64) 或 null | 缓存读取 Token 数。 |
| `cache_write_tokens` | integer (int64) 或 null | 缓存写入总数，直接读取记录值，不将 5m/1h 相加推算。 |
| `cache_write_5m_tokens` | integer (int64) 或 null | 5 分钟缓存写入 Token 数。 |
| `cache_write_1h_tokens` | integer (int64) 或 null | 1 小时缓存写入 Token 数。 |
| `spend` | string 或 null | 实际消费金额，固定 6 位小数。 |
| `original_price` | string 或 null | 按历史综合倍率还原的原价，固定 6 位小数。 |
| `discount_rate` | string 或 null | 历史有效分组倍率 × 用户模型折扣，固定 4 位小数。 |
| `funding_source` | string | 资金来源展示文本，无可用数据时为 `""`。 |
| `currency` | string | 金额币种，默认 `USD`，取决于部署配置。 |

缓存字段缺失、为 null、非整数、负数或超出 int64 时返回 `null`；明确记录的零返回 `0`。响应不包含原始用量凭据，也不包含旧字段 `create_time`。

<Warning>
  JSON 整数可能超过 JavaScript 安全整数范围。需要精确处理超大 Token 数时，应使用无损 JSON 解析；普通 `JSON.parse` 或 `response.json()` 可能丢失精度。
</Warning>

## 金额、折扣和资金来源

金额和折扣均为字符串，使用精确计算和数学意义的向上取整。零金额返回 `"0.000000"`；负金额按同一规则转换。

```text theme={null}
spend = 向上保留6位(quota / QUOTA_PER_UNIT × DISPLAY_CURRENCY_RATE)
original_price = 向上保留6位(ceil(quota / 历史综合倍率) / QUOTA_PER_UNIT × DISPLAY_CURRENCY_RATE)
```

部署默认 `QUOTA_PER_UNIT=500000`、`DISPLAY_CURRENCY=USD`、`DISPLAY_CURRENCY_RATE=1`；汇率表示每 1 USD 对应的展示币种金额，不实时请求外部汇率。调用方应使用响应的 `currency`，不要将默认配置视为固定契约。

折扣使用账单记录时的历史倍率，不读取当前用户、分组或模型折扣。优先使用有效用户分组倍率，否则使用分组倍率，再乘以用户模型折扣。只记录一个有效因子时，缺失因子视为 `1`；完全没有历史倍率或选中的倍率无效时，`discount_rate` 和 `original_price` 为 `null`。原始 quota 为空时，`spend` 和 `original_price` 为 `null`。

原价使用未舍入的历史倍率计算。展示折扣 `"0.3334"` 可能来自实际倍率 `0.333333`，不要用展示折扣重新计算原价。无法识别或损坏的用量凭据会使相关派生字段不可用，不应将 `null` 视为零。

资金来源按测试券、钱包、授信、订阅顺序拼接，例如 `测试券: USD 0.060000 / 钱包: USD 0.100000`。每项独立换算并向上保留 6 位；负 quota 按零展示，缺失或无效项省略，有效零值保留。英文标签为 Voucher、Wallet、Credit、Subscription；币种和数字格式不随语言变化。

## 状态码

| HTTP / code | 中文 msg | 英文 msg | 含义 |
| - | - | - | - |
| `200` | 查询成功 | Success | 当前页有结果。 |
| `202` | 账单未生成，请稍后查询 | Bill not generated yet, please query again later | 当前页无结果。 |
| `400` | 请求参数无效 | Invalid request parameters | 查询参数或编码无效。 |
| `401` | 令牌无效或已过期 | Invalid or expired token | 鉴权失败。 |
| `404` | 接口不存在 | Endpoint not found | 路径不存在。 |
| `405` | 请求方法不允许 | Method not allowed | 已存在路径不支持该方法。 |
| `500` | 服务器内部错误 | Internal server error | 内部异常，且尚未写入响应。 |
| `503` | 服务暂时不可用 | Service temporarily unavailable | 服务依赖失败、超时或记录无法有效解析。 |

```json 无结果（HTTP 202） theme={null}
{"code":202,"msg":"账单未生成，请稍后查询","data":[]}
```

```json 鉴权失败（HTTP 401） theme={null}
{"code":401,"msg":"令牌无效或已过期","data":[]}
```

```json 服务不可用（HTTP 503） theme={null}
{"code":503,"msg":"服务暂时不可用","data":[]}
```

`401` 带 `WWW-Authenticate: Bearer`；对 `/api/usage` 使用不支持的方法返回 `405`，带 `Allow: GET`。失败响应不返回底层错误、凭据或部分日志结果。畸形 HTTP、客户端断连、响应写入中断或代理生成的响应不保证遵循业务 JSON 格式。

## 语言与响应头

支持中文、英文及区域变体，按 `Accept-Language` 的 q 权重选择。缺失、无效或没有匹配时使用简体中文；`zh-TW` 等中文变体也返回简体中文。例如 `zh-CN;q=0.2,en;q=0.9` 优先返回英文。

| 响应头 | 值 |
| - | - |
| `Content-Type` | `application/json; charset=utf-8` |
| `Content-Language` | `zh-CN` 或 `en` |
| `Vary` | `Accept-Language` |
| `Cache-Control` | `no-store` |

## 调用限制与排查

鉴权与日志查询共享请求超时预算，默认 `5s`，部署可配置为大于零且不超过 `1m`。应用当前没有实现限流或 `429` 响应；部署网关可能另有限制。

服务当前没有 CORS 响应头或 OPTIONS 预检处理。浏览器跨域携带 Authorization 调用时，需要部署层提供 CORS 或使用同源代理。

| 现象 | 检查项 |
| - | - |
| 地址栏访问返回 `401` | 地址栏不会添加 Bearer 请求头，使用 cURL 或接口客户端。 |
| 携带令牌仍返回 `401` | 检查 API Key 格式和有效性。 |
| 返回 `400` | 检查未知/重复参数、空值、范围与 URL 编码。 |
| 返回 `202` | 核对请求 ID、API Key 所属用户和 offset；稍后重试。 |
| 返回 `503` | 稍后重试；持续失败时联系服务维护方。 |

<script src="/public/feedback.js" />


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