按路径查询沙箱实例
更新时间:2026-11-17
接口描述
分页列出当前账号下的沙箱实例(E2B v2 兼容),支持按 metadata、状态过滤,按创建时间倒序返回,使用响应头 X-Next-Token 游标翻页。与“分页列出沙箱实例”(GET /v2/sandboxes)为同一实现,仅路径不同。默认返回 running 和 paused 状态;默认不返回由平台托管的沙箱(metadata 含 baidubce_managedBy),在 metadata 过滤条件中显式指定 baidubce_managedBy 时才返回。
API Explorer
去调试
您可以在 API Explorer 中直接运行该接口,运行成功后可自动生成 SDK 代码示例。
请求结构
Plain Text
1GET /sandboxes/v2 HTTP/1.1
2Host: api.sandbox-execute.bj.baidubce.com
3Authorization: authorization string
请求头域
除公共头域外,无其他特殊头域。Authorization 支持 IAM API Key(Bearer bce-v3/ALTAK-...)或 AK/SK 签名(bce-auth-v1/...)。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| limit | Integer | 否 | Query参数 | 单页数量,默认 100;小于 1、大于 100 或非数字时按 100 处理。 |
| nextToken | String | 否 | Query参数 | 分页游标,取上一页响应头 X-Next-Token 的值;首页不传。 |
| metadata | String | 否 | Query参数 | metadata 过滤条件,格式为 URL 编码后的 key=value&key2=value2,多个条件之间为 AND。 |
| state | String | 否 | Query参数 | 状态过滤,可选 running、paused,可重复传入(state=running&state=paused)或逗号分隔(state=running,paused);不传默认 running 和 paused。 |
返回状态码
成功返回 200。服务端查询失败返回 500(Failed to list sandboxes);认证失败返回 403。该接口受服务端访问控制与限流保护,被拒绝时返回 403(AccessDeniedException)或 429(TooManyRequestsException,带 Retry-After)。
返回头域
| 头域 | 描述 |
|---|---|
| X-Total-Running | 满足状态过滤条件的沙箱总数,每次都返回。注意:当前仅按状态计数,未计入 metadata 过滤条件。 |
| X-Next-Token | 下一页游标,仅在还有下一页时返回;不返回表示已是最后一页。 |
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| sandboxes | List |
注意:响应体本身就是 ListedSandbox 数组(JSON 数组,没有外层对象),sandboxes 只是本表的占位名称,请按响应示例解析。 |
请求示例
Plain Text
1GET /sandboxes/v2?limit=20&state=running,paused HTTP/1.1
2Host: api.sandbox-execute.bj.baidubce.com
3Authorization: authorization string
响应示例
Plain Text
1HTTP/1.1 200 OK
2Content-Type: application/json
3X-Total-Running: 21
4X-Next-Token: MjAyNi0xMS0xNlQxNDowMDowMCswODowMF9fc2FuZGJveC0x
5
6[
7 {
8 "sandboxID": "sandbox-1",
9 "templateID": "openclaw-lite",
10 "alias": "openclaw-lite",
11 "clientID": "",
12 "state": "paused",
13 "cpuCount": 2,
14 "memoryMB": 2048,
15 "diskSizeMB": 10240,
16 "startedAt": "2026-11-16T14:00:00+08:00",
17 "endAt": "2026-11-16T15:00:00+08:00",
18 "envdVersion": "0.1.4"
19 }
20]
评价此篇文章
