List sandboxes for administration

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

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

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.

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.

Request parameters

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"

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.

Successful response

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

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 for all public nested fields. Omission and null are described separately.

Error responses

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

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 for the recovery phases.

Last updated on