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

# 查询套餐用量

Step Plan 套餐用量可以在开放平台用户中心查看，也可以通过查询接口获取。

## 在用户中心查看

进入[用户中心](https://platform.stepfun.com/account-overview)的「用量和费用」页面，在「使用详情」的 Step Plan 标签页查看当前套餐周期的 Credit 用量进度、套餐到期时间与调用明细。调用明细按调用时间与模型列出调用次数、输入/输出/缓存 Token 数与 Credit 用量。

## 通过 API 查询

查询接口返回查询时刻的套餐额度快照，只包含总额度与剩余额度，不包含调用明细。额度数值以 Credit 为单位，Credit 与支付金额的换算、套餐档位见[套餐与计费](https://platform.stepfun.com/docs/zh/step-plan/pricing.md)。

### 请求地址

`GET https://api.stepfun.com/step_plan/v1/usage`

### 请求示例

> [tab] curl
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> curl https://api.stepfun.com/step_plan/v1/usage \
>   -H "Authorization: Bearer $STEP_API_KEY"
> ```

> [tab] python
>
> ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> import requests
>
> url = "https://api.stepfun.com/step_plan/v1/usage"
>
> headers = {
>     "Authorization": "Bearer YOUR_STEP_API_KEY"
> }
>
> response = requests.get(url, headers=headers)
>
> print(response.text)
> ```

### 响应示例

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "schema_version": 1,
  "observed_at_ms": 1767196800000,
  "scope": "personal_account",
  "account": {
    "id": "123456789012345678"
  },
  "plan": {
    "state": "known",
    "family": "token",
    "name": "Token-Plus-月付-官方原价",
    "subscription": {
      "id": "123456",
      "expires_at_ms": 1769875200000
    }
  },
  "quota": {
    "state": "known",
    "allowed": true,
    "reason": null,
    "windows": [],
    "credit_buckets": [
      {
        "type": "subscription",
        "total": "1600000000",
        "remaining": "983000000",
        "used_percent": 38.5625,
        "resets_at_ms": null,
        "expires_at_ms": 1769875200000
      }
    ]
  }
}
```

### 响应字段

| 字段 | 类型 | 说明 |
| :- | :- | :- |
| `schema_version` | integer | 响应结构的版本号，当前为 `1` |
| `observed_at_ms` | integer | 用量数据的观测时间，Unix 毫秒时间戳 |
| `scope` | string | 数据所属范围，个人账号返回 `personal_account` |
| `account.id` | string | 账号 ID |
| `plan.state` | string | 套餐状态 |
| `plan.family` | string | 套餐类型，Token Plan 返回 `token` |
| `plan.name` | string | 套餐名称 |
| `plan.subscription.id` | string | 订阅 ID |
| `plan.subscription.expires_at_ms` | integer | 订阅到期时间，Unix 毫秒时间戳 |
| `quota.state` | string | 额度状态 |
| `quota.allowed` | boolean | 当前是否允许发起调用 |
| `quota.reason` | string | `allowed` 为 `false` 时的原因，允许调用时为 `null` |
| `quota.windows` | array | 额度窗口列表 |
| `quota.credit_buckets[].type` | string | 额度来源类型，套餐订阅返回 `subscription` |
| `quota.credit_buckets[].total` | string | 总额度，以 Credit 为单位的整数字符串 |
| `quota.credit_buckets[].remaining` | string | 剩余额度，以 Credit 为单位的整数字符串 |
| `quota.credit_buckets[].used_percent` | float | 已用额度占总额度的百分比 |
| `quota.credit_buckets[].resets_at_ms` | integer | 额度重置时间，Unix 毫秒时间戳，不重置时为 `null` |
| `quota.credit_buckets[].expires_at_ms` | integer | 该额度桶的到期时间，Unix 毫秒时间戳 |

### 认证失败

API Key 缺失或无效时返回 401：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_api_key"
  }
}
```


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