# List Workspace sandboxes

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

Read managed Workspace sandboxes visible to the current identity. Save returned IDs for detail queries.

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

## Before you call this API

Prepare a personal access token and operation privileges for the target Workspace. Keep environment, token, Workspace, and sandbox IDs consistent. [Shared objects and result confirmation](objects.md) explains resource identities, fields, and states. Replace example resource values with actual values.

## Request

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

```bash
curl "https://api.moi.matrixorigin.cn/v5/agent-sandboxes" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} Parameters

This API has no public page, offset, or filter parameters. The array is permission-filtered and excludes objects being deleted or whose creation registration is incomplete. An empty array does not establish that the Workspace globally has no sandboxes.

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

## Successful response

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": [
    {
      "id": "sbx-example",
      "workspace_id": "workspace-example",
      "user_id": "user-example",
      "name": "audit-runner",
      "phase": "ready",
      "edge_agent_id": "sbx-example",
      "network_mode": "limited",
      "network_tools": [
        "git",
        "curl"
      ],
      "egress_endpoints": [
        {
          "host": "example.com",
          "ports": [
            443
          ]
        }
      ],
      "spec": "medium",
      "disk_gi": 10,
      "created_at": "2026-11-11T08:00:00Z",
      "updated_at": "2026-11-11T08:00:00Z",
      "update_available": null
    }
  ]
}
```

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

Meaning of HTTP 200 data below. Example values are not default configuration.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response description. |
| `data` | object (array of objects) | Visible managed sandboxes; see shared objects for fields. |

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

## Confirm the result

Read actual IDs from data[].id, then [Get details](get-sandbox.md). Session-runtime ephemeral sandboxes are excluded from this list.

## Error handling

Check HTTP status and response code. [Shared errors and recovery](objects.md#错误与恢复) distinguishes parameter, permission, quota, provider, and unknown-result cases. Errors do not prove that no resource was created or that retry/cleanup completed.
