# 查询智能体组账户的配额消耗状态

`GET` `/api/tokenBudget/listScopedQuotaStatus`

查询指定身份主体名下全部智能体组账户（仅在一组智能体上生效、组内共享额度，一组可只含一个智能体），每项结构与「查询配额状态」相同，且 scopeAgents 必不为空，列出该组的智能体及名称（智能体已删除时名称为空）。不含全局账户，全局账户请用「查询配额状态」不传 scopeAgentId 查询。主体没有任何智能体组账户时返回空列表。页面可用本接口决定是否展示按智能体的额度分组。

## 请求参数

### 请求头参数

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

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | array | 响应数据 |
|     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处理 |