# 查询配额状态

`GET` `/api/tokenBudget/getQuotaStatus`

查询指定身份主体当前的配额管控状态，包含绑定的策略、周期额度、已用与剩余额度、下次重置时间。不传 scopeAgentId 查询主体的全局账户；传入共享配额的一组智能体中任意一个智能体的ID，查询该智能体所属智能体组账户，同一组内不同智能体ID的查询结果一致，scopeAgents 列出该组的全部智能体。两类账户叠加生效、任一耗尽即拦截，因此判断主体在某智能体上能否使用，需同时查看全局账户与该智能体所在组账户的 blocked。页面展示额度入口时请直接使用 limited 字段，仅 limited 为 true 的用户需要展示。判断主体能否正常使用只需看 blocked 字段：仅当已绑定策略且额度耗尽时为 true。若所查账户尚未绑定配额策略（如该智能体不在主体的任何智能体组中），接口正常返回且 bound 为 false，表示不受该账户管控。加油包明细请用「查询加油包列表」接口查询。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| scopeAgentId | integer | 否 | 共享配额的一组智能体中任意一个智能体的ID（可选）。不传表示全局账户；传入时按该智能体所属智能体组定位到对应账户，同一组内不同智能体ID的定位结果一致 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | TokenBudgetQuotaStatusVO | 响应数据 |
|     bound | boolean | 是否已绑定配额策略；false 表示该主体不受配额管控，可不限额使用，额度相关字段均为空 |
|     limited | boolean | 当前是否属于限额用户；仅当已绑定配额策略且策略明确未失效时为 true。前端应仅在本字段为 true 时展示额度入口 |
|     blocked | boolean | 是否正被配额拦截：仅当已绑定策略且额度耗尽时为 true；未绑定（不受管控）或策略已失效均为 false，表示可正常使用。判断能否使用请直接看本字段 |
|     scopeAgentId | integer | （已废弃，请使用 scopeAgents）智能体组账户中单个智能体ID；仅当该组只含一个智能体时有值。为空可能是全局账户，也可能是一组多个智能体共享的智能体组账户，请以 scopeAgents 判断 |
|     agentName | string | （已废弃，请使用 scopeAgents）智能体组账户中单个智能体名称；仅当该组只含一个智能体且名称解析成功时有值 |
|     scopeAgents | array | 该账户覆盖的智能体列表；为空表示这是主体的全局账户（在全部智能体上生效），非空表示这是一个智能体组账户（仅在列表内智能体上生效、组内智能体共享同一份额度）。未绑定时为空 |
|         agentId | integer | 智能体ID |
|         agentName | string | 智能体名称；智能体已删除或名称查询失败时为空 |
|     policyId | integer | 绑定的配额策略ID |
|     policyName | string | 绑定的配额策略名称；策略已被删除时为空 |
|     totalTokens | integer | 每个周期的主额度上限（Token 数） |
|     usedTokens | integer | 当前周期已消耗的主额度Token数；已跨过重置时点时按0展示 |
|     remainingTokens | integer | 总剩余可用Token数，等于 mainRemainingTokens 与 topupRemainingTokens 之和，永不为负 |
|     mainRemainingTokens | integer | 主额度剩余Token数 |
|     topupRemainingTokens | integer | 有效加油包剩余Token数之和（已排除过期与已撤销的加油包） |
|     exhausted | boolean | 是否已耗尽（诊断用途；判断能否使用请直接看 blocked） |
|     expired | boolean | 配额策略是否已失效（策略到期或已被删除）；失效期间不参与管控，即不限额（诊断用途；判断能否使用请直接看 blocked） |
|     nextResetAt | string | 下一次额度重置时间；策略不重置或已失效时为空 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |