批量查询沙箱实例
更新时间：2026-08-14
接口描述
批量查询当前认证账号下的沙箱实例，支持按沙箱 ID、镜像地址、metadata 和状态过滤，并使用 nextToken 分页。
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
5Accept: application/json请求头域
除公共头域外，无其他特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| limit | Integer | 否 | RequestBody参数 | 单页返回数量，取值 1-100，默认 100。 |
| nextToken | String | 否 | RequestBody参数 | 上一页返回的游标，首次请求为空。 |
| sandboxIds | List |
否 | RequestBody参数 | 沙箱实例 ID 列表，同组内 OR。 |
| imagePaths | List |
否 | RequestBody参数 | 实际镜像地址列表，同组内 OR。 |
| metadata | Map<String,String> | 否 | RequestBody参数 | metadata 键值过滤，条件之间 AND。 |
| state | List |
否 | RequestBody参数 | 沙箱状态列表，可选 running、paused、killing、killed。 |
返回状态码
成功返回 200，失败返回公共错误码。
返回头域
除公共头域外，无其他特殊头域。
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| sandboxes | List |
满足条件的沙箱实例列表。 |
| nextToken | String | 下一页游标，为空表示没有更多数据。 |
请求示例
Plain Text
1{
2 "limit": 20,
3 "nextToken": "",
4 "sandboxIds": [
5 "sandbox-1",
6 "sandbox-2"
7 ],
8 "imagePaths": [
9 "ccr-registry.baidubce.com/agent-sandbox/openclaw-lite:20260610"
10 ],
11 "metadata": {
12 "app": "agent"
13 },
14 "state": [
15 "running",
16 "paused"
17 ]
18}响应示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json
3
4{
5 "sandboxes": [
6 {
7 "sandboxID": "sandbox-1",
8 "state": "running",
9 "metadata": {
10 "app": "agent"
11 },
12 "cpuCount": 2,
13 "memoryMB": 2048,
14 "startedAt": "2026-08-11T14:00:00+08:00",
15 "endAt": "2026-08-11T15:00:00+08:00",
16 "envdVersion": "0.1.4",
17 "envdAccessToken": "",
18 "templateID": "openclaw-lite",
19 "imagePath": "ccr-registry.baidubce.com/agent-sandbox/openclaw-lite:20260610"
20 }
21 ],
22 "nextToken": ""
23}评价此篇文章