<span id="查询沙箱管理列表"></span>

# List sandboxes for administration

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

Filter hosted sandboxes across workspaces by target workspace. This is not a list of temporary execution environments or pooled resources.

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

<span id="调用前准备"></span>

## Before you call this API

Prepare an identity valid in the current environment, configured administrator eligibility, and an accessible authentication workspace. A workspace Owner or Genesis taas:admin does not automatically qualify as this administrator. The example uses a personal access token and exactly one X-Workspace-ID. See [AI Studio](../../../../../developer/api/ai-studio/index.md).

The current Provider retrieves at most 200 remote entries per batch and scans at most 2000. offset is applied after filtering temporary, pooled, and workspace-less resources and hidden business creation/deletion intents. Completeness, stable ordering, and snapshot consistency are not guaranteed. has_more does not guarantee unlimited pagination.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | string | Yes in this example | A personal access token valid in the current environment for a configured administrator. Confirm other ordinary authentication methods, such as Bearer, for the environment. |
| `X-Workspace-ID` | string | Yes | Exactly one nonempty authentication workspace header. This is not a target filter or the workspace whose quota is managed. |
| `limit` | integer | No | Defaults to 50; the service also treats explicit 0 as 50. Valid range: 1–200. |
| `offset` | integer | No | Defaults to 0; must be nonnegative and satisfy offset+limit+1≤2000. An offset of 1999 is not necessarily valid. |
| `workspace_id` | string | No | Target workspace filter. Omission searches across workspaces, separate from the authentication header. |

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | OK on success. |
| `data` | object | Success data. |
| `data.items` | object (array of objects) | Hosted sandboxes on the current page, excluding temporary and pooled resources. |
| `data.limit` | integer | Page limit; there is no total field. |
| `data.offset` | integer | Offset within the filtered matching set. |
| `data.has_more` | string | More results may exist. Can also be true when the scan budget is exhausted; this does not guarantee unbounded continuation. |
| `data.items[].workspace` | object, optional | Optional administration projection. The current Provider supplies at least ID/owner_id; names and account names are not guaranteed. |
| `data.items[].id` | string | Object identifier; currently the remote resource name for a sandbox. |
| `data.items[].workspace_id` | string | Workspace that owns the resource, separate from the authentication header workspace. |
| `data.items[].user_id` | string | User information recorded in remote resource labels. |
| `data.items[].name` | string | Display name. |
| `data.items[].phase` | string | unknown, provisioning, ready, error, or deleting. This is not the complete IAM cleanup state. |
| `data.items[].edge_agent_id` | string | Associated execution environment identifier. |
| `data.items[].network_mode` | string | Currently limited or unrestricted; may be empty when historical labels are absent. This update does not switch modes. |
| `data.items[].network_tools` | string (array of strings), optional | Tool egress allowlist; may be omitted when empty. |
| `data.items[].egress_endpoints` | object (array of objects), optional | Explicit host/ports egress allowlist; may be omitted when empty. |
| `data.items[].spec` | string | Specification projection; may be empty when reading historical labels. Creation enums do not imply required fields for historical records. |
| `data.items[].disk_gi` | integer | Disk size in GiB. May be 0 when remote labels are absent or unparseable; this does not permit creation with 0. |
| `data.items[].compute_resource_id` | string, optional | Optional associated compute resource ID. |
| `data.items[].created_at` | string | Creation time in RFC3339. |
| `data.items[].updated_at` | string | Update time in RFC3339 format; not guaranteed to support concurrent version control. |
| `data.items[].update_available` | boolean / null | boolean or null. null means insufficient information to compare the current image, not false. |

See [common objects](objects.md) for all public nested fields. Omission and null are described separately.
:::::
::::::
:::::::

<span id="错误响应"></span>

## Error responses

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code for the current phase. |
| `msg` | string | Error message; service-classified errors are usually localized. |

| HTTP / code | Conditions and handling |
| --- | --- |
| 400 / ErrParamInvalid | Authentication workspace is missing, request decoding or integer parsing failed, or quota fields are invalid. |
| 400 / SANDBOX_INVALID_SPEC | Service validation failed, for example for a list window or network tool. SPEC in the name does not restrict it to creation specifications. |
| 403 / COMPUTE_RESOURCE_SPEC_FORBIDDEN | The current principal is not a configured administrator, or the identity does not match at the permission-check boundary. |
| 503 / COMPUTE_RESOURCE_SPEC_ADMIN_UNAVAILABLE | Classified unavailability of administrator directory or authorization information. |
| 404 / SANDBOX_NOT_FOUND | Unmanaged, temporary, or pooled resource; nonexistent resource; or a hidden creation/deletion phase. |
| 503 / SANDBOX_IAM_UNAVAILABLE or SANDBOX_NETWORK_STORAGE_UNAVAILABLE | Lifecycle identity or network persistence dependencies are unavailable. |
| 500 / SANDBOX_ERROR or ErrServer | Unclassified Provider or other failures, or localization failure. These do not all return 503. |

See [errors and recovery](errors-recovery.md) for the recovery phases.
:::::
::::::
:::::::
