# 查询沙箱配额与网络能力

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

读取工作区托管沙箱占用和上限；需要时显式请求不受限网络能力。

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

## 调用前准备

准备目标工作区的个人访问令牌与相应操作权限；环境、令牌、工作区和沙箱 ID 保持一致。[公共对象和结果确认](objects.md)说明资源身份、字段及状态。示例的资源值须替换为实际值。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

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

### 包含网络能力

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

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `include_network_capabilities` | boolean | 否 | 查询参数；默认 false。true 时额外返回 unrestricted_network_allowed。 |

同名参数只允许出现一次；无法解析的布尔值或重复参数返回 400。current 包含服务观察到的远端和未完成持久化分配，不等于可见列表长度。此 GET 不返回完整临时沙箱配置。

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

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

以下示例对应 include_network_capabilities=true；默认请求不包含 unrestricted_network_allowed。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "current": 1,
    "limit": 3,
    "default_egress_endpoints": [],
    "unrestricted_network_allowed": false
  }
}
```

:::::
:::::{tab-item} 字段说明

HTTP 200 的数据含义如下；示例值不是默认配置。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应说明。 |
| `data.current` | integer | 托管分配占用。 |
| `data.limit` | integer | 托管分配上限。 |
| `data.default_egress_endpoints` | object（对象数组） | 部署提供的默认出站端点。 |
| `data.unrestricted_network_allowed` | boolean | 仅显式 include_network_capabilities=true 时返回；缺失不等于 false。 |

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

## 结果确认

比较 current 与 limit，但创建仍会重新检查配额与授权。能力字段 false 时不能创建 unrestricted。

## 错误处理

按 HTTP 状态及响应 code 判断；[公共错误与恢复](objects.md#错误与恢复)区分参数、权限、配额、提供商和结果未知。错误不证明尚未产生资源，也不能当成重试或清理已经完成。
