<span id="读取沙箱管理详情"></span>

# Get sandbox administration details

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

Read a manageable hosted sandbox and apply its saved network override configuration.

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

<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).

A 404 can also mean a temporary or pooled resource, or a resource hidden by a business creation/deletion intent. One 404 does not prove that all remote resources, credentials, and ownership have been cleaned up. update_available:null retains its meaning of unknown.

<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/sandbox-example" \
  -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. |
| `id` | string | Yes | Sandbox ID in the path. |

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

<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": {
    "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
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | OK on success. |
| `data` | object | Success data. |
| `data.workspace` | object, optional | Optional administration projection. The current Provider supplies at least ID/owner_id; names and account names are not guaranteed. |
| `data.id` | string | Object identifier; currently the remote resource name for a sandbox. |
| `data.workspace_id` | string | Workspace that owns the resource, separate from the authentication header workspace. |
| `data.user_id` | string | User information recorded in remote resource labels. |
| `data.name` | string | Display name. |
| `data.phase` | string | unknown, provisioning, ready, error, or deleting. This is not the complete IAM cleanup state. |
| `data.edge_agent_id` | string | Associated execution environment identifier. |
| `data.network_mode` | string | Currently limited or unrestricted; may be empty when historical labels are absent. This update does not switch modes. |
| `data.network_tools` | string (array of strings), optional | Tool egress allowlist; may be omitted when empty. |
| `data.egress_endpoints` | object (array of objects), optional | Explicit host/ports egress allowlist; may be omitted when empty. |
| `data.spec` | string | Specification projection; may be empty when reading historical labels. Creation enums do not imply required fields for historical records. |
| `data.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.compute_resource_id` | string, optional | Optional associated compute resource ID. |
| `data.created_at` | string | Creation time in RFC3339. |
| `data.updated_at` | string | Update time in RFC3339 format; not guaranteed to support concurrent version control. |
| `data.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.
:::::
::::::
:::::::
