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 |
|---|---|---|---|
|
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. |
|
string |
Yes |
Exactly one nonempty authentication workspace header. This is not a target filter or the workspace whose quota is managed. |
|
integer |
No |
Defaults to 50; the service also treats explicit 0 as 50. Valid range: 1–200. |
|
integer |
No |
Defaults to 0; must be nonnegative and satisfy offset+limit+1≤2000. An offset of 1999 is not necessarily valid. |
|
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 |
|---|---|---|
|
string |
OK on success. |
|
string |
OK on success. |
|
object |
Success data. |
|
object (array of objects) |
Hosted sandboxes on the current page, excluding temporary and pooled resources. |
|
integer |
Page limit; there is no total field. |
|
integer |
Offset within the filtered matching set. |
|
string |
More results may exist. Can also be true when the scan budget is exhausted; this does not guarantee unbounded continuation. |
|
object, optional |
Optional administration projection. The current Provider supplies at least ID/owner_id; names and account names are not guaranteed. |
|
string |
Object identifier; currently the remote resource name for a sandbox. |
|
string |
Workspace that owns the resource, separate from the authentication header workspace. |
|
string |
User information recorded in remote resource labels. |
|
string |
Display name. |
|
string |
unknown, provisioning, ready, error, or deleting. This is not the complete IAM cleanup state. |
|
string |
Associated execution environment identifier. |
|
string |
Currently limited or unrestricted; may be empty when historical labels are absent. This update does not switch modes. |
|
string (array of strings), optional |
Tool egress allowlist; may be omitted when empty. |
|
object (array of objects), optional |
Explicit host/ports egress allowlist; may be omitted when empty. |
|
string |
Specification projection; may be empty when reading historical labels. Creation enums do not imply required fields for historical records. |
|
integer |
Disk size in GiB. May be 0 when remote labels are absent or unparseable; this does not permit creation with 0. |
|
string, optional |
Optional associated compute resource ID. |
|
string |
Creation time in RFC3339. |
|
string |
Update time in RFC3339 format; not guaranteed to support concurrent version control. |
|
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 |
|---|---|---|
|
string |
Error code for the current phase. |
|
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.