# 查询加油包列表

`GET` `/api/tokenBudget/listTopups`

查询指定身份主体某个配额账户名下的全部加油包明细（含加油包ID，可用于撤销）。不传 scopeAgentId 查询全局账户的加油包；传入共享配额的一组智能体中任意一个智能体的ID，查询这组智能体共享账户的加油包。返回结果含已过期、已耗尽的加油包（由 expired、exhausted 标记区分），不含已撤销的加油包。若所查账户尚未绑定配额策略，返回空列表。

## 请求参数

### 请求头参数

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

### Query 参数

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

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | array | 响应数据 |
|     topupId | integer | 加油包ID，撤销加油包时需传入 |
|     totalTokens | integer | 加油包额度（充值时的Token总量） |
|     usedTokens | integer | 加油包已消耗Token数（独立追踪，不随周期重置） |
|     remainingTokens | integer | 加油包剩余Token数；已过期的加油包剩余额度已作废，但此处仍如实展示 |
|     expireAt | string | 加油包失效时间，为空表示长期有效直到用完 |
|     expired | boolean | 是否已过期；过期后剩余额度作废且不退还 |
|     exhausted | boolean | 是否已用尽（已用量达到额度上限） |
|     remark | string | 充值时填写的备注 |
|     gmtCreate | 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处理 |