> ## 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.

# GET /api/usage

> Query request logs, token usage, billing amounts, and funding sources for the user associated with your API key.

`GET /api/usage` queries logs and billing records by an exact `request_id` match, within the user associated with your API key. One query can return multiple records; request IDs are not guaranteed to be unique.

<Info>
  This page follows the API contract dated October 13, 2026. Queries against actual business logs have not been verified. The overseas query node is `https://reqs.anyfast.ai`.
</Info>

## Quick example

```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: en' \
  --data-urlencode 'request_id=req-001' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'offset=0'
```

Send URL query parameters without a request body. Use `/api/usage` exactly; `/api/usage/` returns `404`.

## Authentication

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer sk-YOUR_API_KEY`. Only one Authorization header is allowed. |
| `Accept-Language` | No | Sets the language of messages and funding source labels. Defaults to Simplified Chinese. |

`Bearer` is case-insensitive. The API key must begin with lowercase `sk-`, have a nonempty value after the prefix, and contain no whitespace. Missing prefixes, `SK-`, a bare `sk-`, duplicate headers, or invalid tokens return `401`.

Authentication precedes parameter validation. An invalid token with invalid parameters returns `401` first.

Queries always use the user associated with your API key. You cannot select another user through `user_id`, `X-User-ID`, or other headers. An explicit `user_id` query parameter returns `400`. Records belonging to other users are excluded even if their request IDs match.

## Query parameters

| Parameter | Type | Required | Default | Constraints |
| - | - | - | - | - |
| `request_id` | string | Yes | None | Exact match. Must not be empty or whitespace-only. No `sk-` prefix or application-level 256-byte length limit. |
| `limit` | integer | No | `100` | Page size, from `1` to `1000`, inclusive. |
| `offset` | integer | No | `0` | Records to skip, from `0` to `1000000`, inclusive. |

Parameter names are case-sensitive. A nonempty request ID retains its leading and trailing spaces for exact matching.

The endpoint returns `400` for a missing or whitespace-only request ID, unknown parameters, repeated parameters, explicit empty values, invalid integer formats or ranges, and invalid query-string encoding. Time ranges, model filters, custom sorting, `page`, and `user_id` are not supported.

## Pagination and ordering

Start with `offset=0`, then increase the offset by the number of records actually returned. Responses contain only the current page, without `total`, `has_more`, or a cursor.

Fewer than `limit` records indicate the last page for this query. Exactly `limit` records may be followed by an empty page. Every empty page returns `202`, including offsets beyond the available records.

<Warning>
  `202` only means this query returned no records. It does not establish billing generation progress. During writes or updates, offset pagination can repeat or omit records and provides no snapshot consistency.
</Warning>

Records are ordered by creation time descending, request ID ascending, input tokens descending, output tokens descending, model name ascending, quota descending, af\_usage ascending, and other ascending. Nulls in the last three fields sort last. Results are stable while data remains unchanged; identical records are not deduplicated.

## Successful response

HTTP `200`. The following values are illustrative:

```json theme={null}
{
  "code": 200,
  "msg": "Success",
  "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": "Wallet: USD 0.200002",
      "currency": "USD"
    }
  ]
}
```

Every business JSON response includes `code` (equal to the HTTP status), `msg` (a localized message), and `data` (an array). Empty or failed responses use `[]`, never `null`. Branch on the status or `code` rather than message text.

## Log fields

| Field | Type | Description |
| - | - | - |
| `request_id` | string | Request identifier. |
| `prompt_tokens` | integer (int64) | Input tokens. A null stored value returns `0`. |
| `completion_tokens` | integer (int64) | Output tokens. A null stored value returns `0`. |
| `total_tokens` | integer (int64) | `prompt_tokens + completion_tokens` for each record. |
| `mode_name` | string | Model name. The response field is spelled `mode_name`, not `model_name`. |
| `request_time` | string | Fixed UTC+8, including brackets and an English month abbreviation, such as `[24/Sep/2026:10:15:32 +0800]`. Unaffected by language or server timezone. |
| `cache_read_tokens` | integer (int64) or null | Cache read tokens. |
| `cache_write_tokens` | integer (int64) or null | Recorded total cache write tokens, not inferred by adding the 5-minute and 1-hour counts. |
| `cache_write_5m_tokens` | integer (int64) or null | Tokens written to the 5-minute cache. |
| `cache_write_1h_tokens` | integer (int64) or null | Tokens written to the 1-hour cache. |
| `spend` | string or null | Actual charge, with six decimal places. |
| `original_price` | string or null | Original price reconstructed from historical combined factors, with six decimal places. |
| `discount_rate` | string or null | Historical effective group factor multiplied by the user model discount, with four decimal places. |
| `funding_source` | string | Funding source display text, or `""` if unavailable. |
| `currency` | string | Amount currency. Defaults to `USD` and depends on deployment configuration. |

Missing, null, noninteger, negative, or out-of-int64-range cache counts return `null`. Explicitly recorded zeros return `0`. The response excludes raw usage receipts and the old `create_time` field.

<Warning>
  JSON integers can exceed JavaScript's safe integer range. Use lossless JSON parsing when exact large token counts matter; ordinary `JSON.parse` or `response.json()` can lose precision.
</Warning>

## Amounts, discounts, and funding sources

Amounts and discounts are strings computed precisely and rounded toward positive infinity. Zero amounts return `"0.000000"`. Negative amounts follow the same rounding rule.

```text theme={null}
spend = round_up_6(quota / QUOTA_PER_UNIT × DISPLAY_CURRENCY_RATE)
original_price = round_up_6(ceil(quota / historical_combined_factor) / QUOTA_PER_UNIT × DISPLAY_CURRENCY_RATE)
```

Deployment defaults are `QUOTA_PER_UNIT=500000`, `DISPLAY_CURRENCY=USD`, and `DISPLAY_CURRENCY_RATE=1`. The exchange rate represents display currency per USD and is not fetched live. Use the response's `currency`; defaults are not a fixed API contract.

Discounts use factors recorded with the bill, rather than current user, group, or model settings. An effective user group factor takes precedence over the group factor, then is multiplied by the user model discount. When only one valid factor is recorded, a missing factor defaults to `1`. If no historical factors exist or a selected factor is invalid, `discount_rate` and `original_price` are `null`. A null original quota makes `spend` and `original_price` null.

Original price uses the unrounded historical factor. A displayed discount of `"0.3334"` can come from an actual factor of `0.333333`; do not recompute original price using the displayed discount. Unrecognized or damaged usage receipts make related derived fields unavailable. Do not interpret `null` as zero.

Funding sources appear in Voucher, Wallet, Credit, Subscription order, for example `Voucher: USD 0.060000 / Wallet: USD 0.100000`. Each amount is independently converted and rounded up to six places. Negative quota is displayed as zero; missing or invalid entries are omitted, while valid zeros remain. Chinese labels are 测试券, 钱包, 授信, 订阅. Currency codes and numeric formatting do not change with language.

## Status codes

| HTTP / code | Chinese msg | English msg | Meaning |
| - | - | - | - |
| `200` | 查询成功 | Success | The current page contains records. |
| `202` | 账单未生成，请稍后查询 | Bill not generated yet, please query again later | The current page is empty. |
| `400` | 请求参数无效 | Invalid request parameters | Invalid query parameters or encoding. |
| `401` | 令牌无效或已过期 | Invalid or expired token | Authentication failed. |
| `404` | 接口不存在 | Endpoint not found | Unknown path. |
| `405` | 请求方法不允许 | Method not allowed | Unsupported method on an existing path. |
| `500` | 服务器内部错误 | Internal server error | An internal exception before the response was written. |
| `503` | 服务暂时不可用 | Service temporarily unavailable | Dependency failure, timeout, or a record that cannot be parsed correctly. |

```json Empty page (HTTP 202) theme={null}
{"code":202,"msg":"Bill not generated yet, please query again later","data":[]}
```

```json Authentication failure (HTTP 401) theme={null}
{"code":401,"msg":"Invalid or expired token","data":[]}
```

```json Service unavailable (HTTP 503) theme={null}
{"code":503,"msg":"Service temporarily unavailable","data":[]}
```

`401` includes `WWW-Authenticate: Bearer`. Unsupported methods on `/api/usage` return `405` with `Allow: GET`. Failures exclude underlying errors, credentials, and partial results. Malformed HTTP, disconnects, interrupted writes, and proxy-generated responses may not follow the business JSON format.

## Language and response headers

Chinese, English, and regional variants are supported, selected by `Accept-Language` q weights. Missing, invalid, or unmatched values default to Simplified Chinese. Chinese variants such as `zh-TW` also return Simplified Chinese. For example, `zh-CN;q=0.2,en;q=0.9` selects English.

| Response header | Value |
| - | - |
| `Content-Type` | `application/json; charset=utf-8` |
| `Content-Language` | `zh-CN` or `en` |
| `Vary` | `Accept-Language` |
| `Cache-Control` | `no-store` |

## Limits and troubleshooting

Authentication and log queries share a request timeout budget, defaulting to `5s`. Deployments can configure a positive timeout up to `1m`. The application currently implements no rate limiting or `429` response; deployment gateways may impose limits.

The service currently provides no CORS response headers or OPTIONS preflight handling. Cross-origin browser requests with Authorization need deployment-level CORS support or a same-origin proxy.

| Symptom | Check |
| - | - |
| Address-bar access returns `401` | Browser navigation does not add a Bearer header; use cURL or an API client. |
| A token still returns `401` | Verify API key format and validity. |
| `400` | Check unknown/repeated parameters, empty values, ranges, and URL encoding. |
| `202` | Check request ID, the API key's user, and offset; retry later. |
| `503` | Retry later; contact the service maintainer if failures persist. |

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


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