批量查询沙箱实例
更新时间:2026-11-17
接口描述
批量查询当前账号下的沙箱实例,支持按沙箱 ID、镜像地址、metadata 和状态组合过滤,按创建时间倒序返回,使用 nextToken 分页。不同过滤条件之间为 AND,同一列表内的取值之间为 OR。与列表接口不同,本接口不排除平台托管沙箱,不传 state 时返回所有状态的沙箱。
API Explorer
去调试
您可以在 API Explorer 中直接运行该接口,运行成功后可自动生成 SDK 代码示例。
请求结构
Plain Text
1POST /sandboxes/query HTTP/1.1
2Host: api.sandbox-execute.bj.baidubce.com
3Authorization: authorization string
4Content-Type: application/json
请求头域
除公共头域外,无其他特殊头域。Authorization 支持 IAM API Key(Bearer bce-v3/ALTAK-...)或 AK/SK 签名(bce-auth-v1/...)。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| limit | Integer | 否 | RequestBody参数 | 单页数量,取值 1~100,不传或 0 为 100,超出范围返回 400。 |
| nextToken | String | 否 | RequestBody参数 | 分页游标,取上一页响应中的 nextToken;首页不传。 |
| sandboxIds | List |
否 | RequestBody参数 | 沙箱实例 ID 列表,最多 100 个,不能包含空字符串。 |
| imagePaths | List |
否 | RequestBody参数 | 沙箱实际镜像地址列表,最多 100 个,不能包含空字符串。 |
| metadata | Map<String,String> | 否 | RequestBody参数 | metadata 过滤条件,沙箱需包含全部键值对。 |
| state | List |
否 | RequestBody参数 | 状态过滤,可选 running、paused、pending、standby、failed、killing、killed;不传则不按状态过滤。传入其他值返回 400。 |
返回状态码
成功返回 200。请求体非法、limit 超出范围、列表超过 100 个或包含空值、state 不支持时返回 400;服务端查询失败返回 500(Failed to query sandboxes);认证失败返回 403。该接口受服务端访问控制与限流保护,被拒绝时返回 403(AccessDeniedException)或 429(TooManyRequestsException,带 Retry-After)。
返回头域
除公共头域外,无其他特殊头域。
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| sandboxes | List |
满足条件的沙箱实例列表。 |
| nextToken | String | 下一页游标;没有下一页时省略该字段。 |
请求示例
Plain Text
1POST /sandboxes/query HTTP/1.1
2Host: api.sandbox-execute.bj.baidubce.com
3Authorization: authorization string
4Content-Type: application/json
5
6{
7 "limit": 20,
8 "sandboxIds": ["sandbox-1", "sandbox-2"],
9 "imagePaths": ["ccr-registry.baidubce.com/agent-sandbox/openclaw-lite:20260610"],
10 "metadata": {
11 "app": "agent"
12 },
13 "state": ["running", "paused"]
14}
响应示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json
3
4{
5 "sandboxes": [
6 {
7 "sandboxID": "sandbox-1",
8 "templateID": "openclaw-lite",
9 "state": "running",
10 "metadata": {
11 "app": "agent"
12 },
13 "cpuCount": 2,
14 "memoryMB": 2048,
15 "startedAt": "2026-11-16T14:00:00+08:00",
16 "endAt": "2026-11-16T15:00:00+08:00",
17 "envdVersion": "0.1.4",
18 "envdAccessToken": "xxxxxxxx",
19 "imagePath": "ccr-registry.baidubce.com/agent-sandbox/openclaw-lite:20260610"
20 }
21 ],
22 "nextToken": "MjAyNi0xMS0xNlQxNDowMDowMCswODowMF9fc2FuZGJveC0x"
23}
评价此篇文章
