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

# 用量查询

> 通过用户管理 API 或当前 API 令牌查询自己的用量日志和用量统计。

用量查询有两类鉴权方式：用量日志和统计接口使用登录会话或管理访问令牌；单个模型调用 API 令牌的用量接口使用该 `sk-` API 令牌鉴权。

## 查询用量日志

```text theme={"system"}
GET /api/log/self?p=1&page_size=20
```

<ParamField path="p" type="integer">
  页码，从 `1` 开始。
</ParamField>

<ParamField path="page_size" type="integer">
  每页条数。
</ParamField>

<ParamField path="type" type="integer">
  按日志类型筛选。
</ParamField>

<ParamField path="token_name" type="string">
  按 API 令牌名称筛选。
</ParamField>

<ParamField path="model_name" type="string">
  按模型名称筛选。
</ParamField>

<ParamField path="group" type="string">
  按分组筛选。
</ParamField>

<ParamField path="request_id" type="string">
  按请求 ID 筛选。
</ParamField>

<ParamField path="start_timestamp" type="integer">
  查询开始时间，Unix 时间戳。
</ParamField>

<ParamField path="end_timestamp" type="integer">
  查询结束时间，Unix 时间戳。
</ParamField>

返回你的用量日志，包含模型、API 令牌、分组、Token 用量、费用和调用状态。

## 查询用量汇总

```text theme={"system"}
GET /api/log/self/stat?start_timestamp=1700000000&end_timestamp=1700100000
```

返回指定时间范围内的用量统计字段，例如 `quota`、`rpm` 和 `tpm`。对账时以控制台使用日志和余额变动为准。

## 查询当前 API 令牌用量

```bash theme={"system"}
curl https://api.aiohub.org/api/usage/token \
  -H "Authorization: Bearer sk-你的API令牌"
```

这个接口返回当前 `sk-` API 令牌的用量总览。它不是登录会话下的“全部 API 令牌列表”接口。

默认返回当前 API 令牌的额度状态：

```json theme={"system"}
{
  "success": true,
  "message": "ok",
  "data": {
    "total_granted": 2,
    "total_used": 0.5,
    "total_available": 1.5,
    "unlimited_quota": false,
    "expires_at": 0
  }
}
```

`total_granted`、`total_used` 和 `total_available` 已按站点当前额度展示口径换算；响应不返回单位或符号。`expires_at` 为 Unix 秒级时间戳；`0` 表示未设置过期时间。

## 查询当前 API 令牌的时间范围用量

```bash theme={"system"}
curl "https://api.aiohub.org/api/usage/token?start_timestamp=1700000000&end_timestamp=1700100000" \
  -H "Authorization: Bearer sk-你的API令牌"
```

同一个接口可通过 `start_timestamp` 和 `end_timestamp` 查询时间范围用量。它适合只有 API 令牌、没有登录会话或管理访问令牌的脚本，只汇总当前 API 令牌自己的消费额度，不返回日志明细。

<ParamField path="start_timestamp" type="integer" required>
  查询开始时间，Unix 秒级时间戳，闭区间包含该秒。与 `end_timestamp` 成对传入；不要传毫秒时间戳。
</ParamField>

<ParamField path="end_timestamp" type="integer" required>
  查询结束时间，Unix 秒级时间戳，闭区间包含该秒。与 `start_timestamp` 成对传入；`end_timestamp` 必须大于或等于 `start_timestamp`。
</ParamField>

带时间范围时，`data` 会增加 `range_used`：

```json theme={"system"}
{
  "success": true,
  "message": "ok",
  "data": {
    "total_granted": 2,
    "total_used": 0.5,
    "range_used": 0.12,
    "total_available": 1.5,
    "unlimited_quota": false,
    "expires_at": 0
  }
}
```

`range_used` 同样使用站点当前额度展示口径，数值保留到 6 位小数。空时间范围会返回成功响应并包含 `range_used: 0`。其他查询参数会被忽略；已禁用或已过期的 API 令牌不能查询，额度耗尽的 API 令牌仍可查询自己的历史汇总。

## 排查建议

* 找不到某条记录时，先确认查询时间范围和页码。
* 按 API 令牌名称、模型、分组和时间窗口交叉筛选。
* 自动化脚本只有 API 令牌时，用 `/api/usage/token` 读取当前 API 令牌总览，并通过 `start_timestamp` / `end_timestamp` 查询时间范围用量。
* 费用和 Token 数以控制台使用日志为准。