# 查询 Key 的额度、余额与用量

> BigModel.io 的 GET /v1/usage 接口：返回当前 Key 的余额或额度、5 小时/1 天/7 天消费窗口、过期时间和 token 用量。Key 过期或额度用完后仍可调用。

网页版: https://bigmodel.io/zh-cn/docs/api-usage · 更新于 2026-10-18

`GET https://bigmodel.io/v1/usage`

返回当前 Key 还剩多少、用了多少：账户余额、套餐额度或 Key 自己的额度、消费窗口、过期时间和 token 统计。任何 Key 都能调用，而且不做计费检查，所以 [CC Switch](https://bigmodel.io/zh-cn/docs/cc-switch) 等工具在 Key 过期或额度用完后仍能显示原因。返回字段随 `mode` 不同。

## 请求

```http
GET https://bigmodel.io/v1/usage
```

### 认证

| 请求头 | 值 |
|---|---|
| `Authorization` | `Bearer $BIGMODEL_API_KEY` |
| `x-api-key` | `$BIGMODEL_API_KEY` |

任选其一。

### 查询参数

| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `start_date` | string |  | `model_stats` 统计起始日期（YYYY-MM-DD），默认 30 天前。 |
| `end_date` | string |  | `model_stats` 统计结束日期（YYYY-MM-DD），默认今天。 |

## 响应

| 状态码 | 含义 |
|---|---|
| `200` | Key 的用量。字段随 `mode` 不同。 |
| `400` | `api_key_in_query_deprecated`：Key 放在了 `?key=` 或 `?api_key=` 里，请改用请求头。 |
| `401` | `API_KEY_REQUIRED`、`INVALID_API_KEY`、`API_KEY_DISABLED`、`USER_NOT_FOUND`、`USER_INACTIVE`。 |
| `403` | `ACCESS_DENIED`（IP 规则）或 `permission_error`（Key 未分配分组）。 |

### 响应字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `mode` | string | Key 设置了自己的额度或限额时为 `quota_limited`，否则为 `unrestricted`（使用账户余额或套餐）。 可选值：`quota_limited`, `unrestricted` |
| `isValid` | boolean | Key 处于正常、额度用完或已过期时都为 true，具体看 `status`。 |
| `status` | string | 仅 `quota_limited`：`active`、`quota_exhausted`、`expired` 等。 |
| `planName` | string | 仅 `unrestricted`：套餐（分组）名或钱包余额。 |
| `remaining` | number | 剩余美元：Key 额度、余额，或套餐各周期中最小的剩余额度（无限制时为 `-1`）。 |
| `unit` | any |  |
| `balance` | number | 使用余额时的钱包余额（美元）。 |
| `quota` | object | 设置了额度的 `quota_limited` Key。 |
| `quota.limit` | number |  |
| `quota.used` | number |  |
| `quota.remaining` | number |  |
| `quota.unit` | any |  |
| `rate_limits` | array<object> | Key 上设置的消费窗口。 |
| `rate_limits[].window` | string | 可选值：`5h`, `1d`, `7d` |
| `rate_limits[].limit` | number |  |
| `rate_limits[].used` | number |  |
| `rate_limits[].remaining` | number |  |
| `rate_limits[].window_start` | string |  |
| `rate_limits[].reset_at` | string |  |
| `expires_at` | string | Key 过期时间（如有）。 |
| `days_until_expiry` | integer |  |
| `subscription` | object | 套餐的额度与已用（美元）。 |
| `subscription.daily_usage_usd` | number |  |
| `subscription.weekly_usage_usd` | number |  |
| `subscription.monthly_usage_usd` | number |  |
| `subscription.daily_limit_usd` | number |  |
| `subscription.weekly_limit_usd` | number |  |
| `subscription.monthly_limit_usd` | number |  |
| `subscription.expires_at` | string |  |
| `usage` | object | 该 Key 的 token 用量，暂不可用时省略。 |
| `usage.today` | object |  |
| `usage.total` | object |  |
| `usage.average_duration_ms` | number |  |
| `usage.rpm` | number |  |
| `usage.tpm` | number |  |
| `model_stats` | array<object> | 日期范围内的分模型用量，暂不可用时省略。 |


## 示例

```bash [cURL]
curl "https://bigmodel.io/v1/usage?start_date=2026-10-01&end_date=2026-10-18" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"
```

```python [Python]
import os, requests

usage = requests.get(
    "https://bigmodel.io/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"},
    timeout=30,
).json()
print(usage["mode"], usage.get("remaining"), usage.get("unit"))
```

```js [Node.js]
const usage = await (await fetch('https://bigmodel.io/v1/usage', {
  headers: {Authorization: `Bearer ${process.env.BIGMODEL_API_KEY}`},
})).json()
console.log(usage.mode, usage.remaining, usage.unit)
```

### 使用账户余额的 Key

数值仅作示意。`usage` 只保留了 `today`，`total` 字段相同。

```json
{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "钱包余额",
  "remaining": 12.5,
  "unit": "USD",
  "balance": 12.5,
  "usage": {
    "today": {"requests": 42, "input_tokens": 51200, "output_tokens": 8300, "cache_creation_tokens": 0, "cache_read_tokens": 20480, "total_tokens": 79980, "cost": 0.091, "actual_cost": 0.091},
    "average_duration_ms": 2350,
    "rpm": 0,
    "tpm": 0
  }
}
```

### 设置了额度和消费窗口的 Key

数值仅作示意；时间戳使用服务器时区。

```json
{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {"limit": 20, "used": 4.2, "remaining": 15.8, "unit": "USD"},
  "remaining": 15.8,
  "unit": "USD",
  "rate_limits": [
    {"window": "5h", "limit": 2, "used": 0.6, "remaining": 1.4, "window_start": "2026-10-18T08:00:00+08:00", "reset_at": "2026-10-18T13:00:00+08:00"}
  ],
  "expires_at": "2026-11-17T00:00:00+08:00",
  "days_until_expiry": 30
}
```

## 说明

- **三种结构。** Key 设置了自己的额度或 5 小时/1 天/7 天消费限额时为 `quota_limited`；Key 所在分组按生效中的套餐计费时为带 `subscription` 的 `unrestricted`；其他情况为带 `balance` 的 `unrestricted`。余额模式下 `planName` 固定为字符串 `钱包余额`。
- **`remaining`** 单位是美元：Key 额度、账户余额，或套餐各周期中最小的剩余额度（套餐无限制时为 `-1`）。
- **`quota_limited` 模式下，Key 过期或额度用完时 `isValid` 仍为 `true`。** 请查看 `status`（`active`、`quota_exhausted`、`expired`）和 `days_until_expiry` 判断 Key 能否继续请求。
- **消费窗口是固定窗口，不是滚动窗口。** 窗口从首次使用时开始，满时长后重置；只有窗口进行中才有 `reset_at`。详见[按 Key 限额与预算](https://bigmodel.io/zh-cn/docs/key-limits)。
- **用量统计尽力返回。** 统计不可用时省略 `usage` 和 `model_stats`。`start_date` / `end_date`（YYYY-MM-DD）只影响 `model_stats`，默认最近 30 天。`cost` 按标价计算，`actual_cost` 是实际扣费。
- **并非所有检查都跳过。** 已禁用的 Key 仍返回 `401` `API_KEY_DISABLED`，IP 规则仍然生效。完整列表见[错误码](https://bigmodel.io/zh-cn/docs/errors)。
- 需要逐条请求明细或导出 CSV，请使用控制台的[用量](https://bigmodel.io/usage)页面。

## 相关文档

- [按 Key 限额与预算](https://bigmodel.io/zh-cn/docs/key-limits)
- [计费与充值](https://bigmodel.io/zh-cn/docs/billing)
- [CC Switch](https://bigmodel.io/zh-cn/docs/cc-switch)