# 查询沙箱管理列表

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

按目标工作区筛选跨工作区托管沙箱；不是临时运行环境或池资源清单。

```text
GET https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes
```

## 调用前准备

准备当前环境有效身份、已配置的管理员资格和可用鉴权工作区；工作区Owner或Genesis的taas:admin并不自动等于这类管理员。示例使用个人访问令牌与唯一 X-Workspace-ID。见[AI Studio](../../../../../developer/api/ai-studio/index.md)。

当前Provider每批最多200、扫描最多2000个远端条目。过滤临时/池/无工作区和隐藏的业务创建/删除意图后才应用offset；不承诺全量、稳定排序或一致性快照。has_more不是无限翻页保证。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0" \
  --data-urlencode "workspace_id=$TARGET_WORKSPACE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $AUTH_WORKSPACE_ID"
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `X-API-Key` | string | 示例是 | 当前环境有效个人访问令牌；需对应已配置管理员主体。Bearer等其他普通认证方式按环境确认。 |
| `X-Workspace-ID` | string | 是 | 唯一非空鉴权工作区头；不是目标筛选或目标配额工作区。 |
| `limit` | integer | 否 | 默认50；显式0在service中也按50，合法范围1至200。 |
| `offset` | integer | 否 | 默认0、非负；还须满足offset+limit+1≤2000，不能写到1999就一定可用。 |
| `workspace_id` | string | 否 | 目标工作区过滤；省略跨工作区，区别于鉴权头。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "workspace": {
          "id": "target-workspace",
          "owner_id": "owner-example"
        },
        "id": "sandbox-example",
        "workspace_id": "target-workspace",
        "user_id": "owner-example",
        "name": "示例沙箱",
        "phase": "ready",
        "edge_agent_id": "sandbox-example",
        "network_mode": "limited",
        "network_tools": [
          "curl"
        ],
        "egress_endpoints": [
          {
            "host": "example.com",
            "ports": [
              443
            ]
          }
        ],
        "spec": "small",
        "disk_gi": 10,
        "created_at": "2026-11-12T06:00:00Z",
        "updated_at": "2026-11-12T06:00:00Z",
        "update_available": null
      }
    ],
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功为OK。 |
| `msg` | string | 成功为OK。 |
| `data` | object | 成功数据。 |
| `data.items` | object（对象数组） | 当前页托管沙箱数组，不包括临时/池资源。 |
| `data.limit` | integer | 本页上限；无total字段。 |
| `data.offset` | integer | 在过滤后的匹配集合中偏移。 |
| `data.has_more` | string | 可能还有结果；扫描达到预算时也可能为true，不保证可继续无界翻页。 |
| `data.items[].workspace` | object，可省略 | 可选管理投影。当前Provider至少提供ID/owner_id，不保证名称或账号名。 |
| `data.items[].id` | string | 对象标识；沙箱当前为远端资源名。 |
| `data.items[].workspace_id` | string | 资源所属工作区；不是鉴权头中的工作区。 |
| `data.items[].user_id` | string | 远端资源标签中的用户事实。 |
| `data.items[].name` | string | 展示名称。 |
| `data.items[].phase` | string | unknown、provisioning、ready、error或deleting；不是完整IAM清理状态。 |
| `data.items[].edge_agent_id` | string | 关联执行环境标识。 |
| `data.items[].network_mode` | string | 当前定义limited或unrestricted；历史标签缺失可为空。本更新不切换模式。 |
| `data.items[].network_tools` | string（字符串数组），可省略 | 工具出网允许列表；为空时可省略。 |
| `data.items[].egress_endpoints` | object（对象数组），可省略 | 显式host/ports出网允许列表；为空时可省略。 |
| `data.items[].spec` | string | 规格投影；读取历史标签可为空，不以创建枚举推断历史必填。 |
| `data.items[].disk_gi` | integer | 磁盘GiB；远端标签缺失/不可解析时可为0，不代表可按0创建。 |
| `data.items[].compute_resource_id` | string，可省略 | 可选关联计算资源ID。 |
| `data.items[].created_at` | string | 创建时间，RFC3339。 |
| `data.items[].updated_at` | string | 更新时间，RFC3339；不保证可用于并发版本控制。 |
| `data.items[].update_available` | boolean / null | boolean或null；null表示当前镜像比较信息不足，不能当false。 |

嵌套对象的全部公开字段见[公共对象](objects.md)，省略与null分别说明。
:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{"code":"ErrParamInvalid","msg":"Bad Request"}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 当前阶段错误代码。 |
| `msg` | string | 错误文本，service分类通常本地化。 |

| HTTP / code | 条件与处理 |
| --- | --- |
| 400 / ErrParamInvalid | 缺少鉴权工作区、请求解码/整数解析失败或配额字段无效。 |
| 400 / SANDBOX_INVALID_SPEC | 列表窗口或网络工具等service校验失败，名称虽含SPEC也不只指创建规格。 |
| 403 / COMPUTE_RESOURCE_SPEC_FORBIDDEN | 当前主体不是配置管理员或权限检查边界身份不匹配。 |
| 503 / COMPUTE_RESOURCE_SPEC_ADMIN_UNAVAILABLE | 已分类的管理员目录/授权事实不可用。 |
| 404 / SANDBOX_NOT_FOUND | 非托管/临时/池资源，资源不存在，或处于被隐藏的创建/删除阶段。 |
| 503 / SANDBOX_IAM_UNAVAILABLE 或 SANDBOX_NETWORK_STORAGE_UNAVAILABLE | 生命周期身份或网络持久化依赖不可用。 |
| 500 / SANDBOX_ERROR 或 ErrServer | 未专门分类的Provider等失败，或本地化失败；不能一律写成503。 |

不同恢复阶段见[错误与恢复](errors-recovery.md)。
:::::
::::::
:::::::
