<span id="暂停计算资源"></span>

# Suspend a compute resource

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

Suspend a target compute instance as a configured administrator, then return the instance reread after the operation.

```text
POST https://api.moi.matrixorigin.cn/v5/admin/compute-resources/{id}/suspend
```

<span id="调用前准备"></span>

## Before you call this API

Prepare a valid identity for this deployment, configured compute specification administrator privileges, and an accessible authentication Workspace. Workspace Owner status or a Genesis administration scope is insufficient. Replace example IDs with targets you are authorized to read or operate on. See [Compute Instances](../../../../../developer/cli/tasks/compute-resources.md).

Confirm that the parent instance is ACTIVE and the runtime service is available. Suspension acquires a lease, stops Workers, persists the final state, and then rereads the instance. An unfinished lease or Cloud teardown can return 409; automatic resubmission does not bypass it. The current typed compute resource models across the three clients do not declare nonempty py_requirements_txt/sha response fields. Confirm compatibility for instances with custom dependencies separately. Preserve the status and response through raw HTTP. After a client decoding error, reread before concluding that the operation did not occur.

<span id="请求参数"></span>

## Request parameters

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/admin/compute-resources/cr-example/suspend" \
  -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 valid personal access token for an identity configured as a compute specification administrator in this deployment. |
| `X-Workspace-ID` | string | Yes | One nonempty authentication Workspace accessible to the current principal; not a target instance Workspace filter. |
| `id` | string | Yes | Target instance ID. The service resolves its actual Workspace from this ID. |

This API does not read a business request body. Do not submit the target Workspace or state through the body.
:::::
::::::
:::::::

<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": {
    "id": "cr-example",
    "workspace_id": "target-workspace",
    "name": "示例实例",
    "description": "",
    "kind": "task",
    "spec_id": "spec-example",
    "cpu": 1,
    "memory_gib": 4,
    "gpu": 0,
    "cpu_milli": 1000,
    "memory_mib": 4096,
    "gpu_count": 0,
    "gpu_memory_mib": 0,
    "gpu_cores": 0,
    "min_replicas": 0,
    "max_replicas": 2,
    "current_replicas": 0,
    "desired_replicas": 0,
    "go_worker_image_id": "",
    "python_worker_image_id": "",
    "worker_images": [
      {
        "worker_type": "python-worker",
        "image_id": "image-example",
        "platform": "linux"
      }
    ],
    "platform": "linux",
    "auto_suspend_minutes": 30,
    "scale_reason": "manual_suspend",
    "is_default": false,
    "status": "SUSPENDED",
    "status_message": "",
    "created_by": "creator-example",
    "allowed_actions": [],
    "created_at": "2026-11-12T07:00:00Z",
    "updated_at": "2026-11-12T07:00:00Z"
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | OK on success. |
| `data` | object | Data read now or after the operation. |
| `data.id` | string | Compute instance ID. |
| `data.workspace_id` | string | The instance's actual Workspace, separate from the authentication header. |
| `data.name` | string | Instance name. |
| `data.description` | string | Instance description; may be an empty string. |
| `data.kind` | string | task or query. |
| `data.spec_id` | string | Associated specification ID. |
| `data.cpu` | integer | Legacy CPU specification field, in cores; do not confuse it with cpu_milli. |
| `data.memory_gib` | integer | Legacy memory specification field, in GiB. |
| `data.gpu` | integer | Legacy GPU specification field. |
| `data.cpu_milli` | integer | Specification CPU, in millicores. |
| `data.memory_mib` | integer | Specification memory, in MiB. |
| `data.gpu_count` | integer | Specification GPU count. |
| `data.gpu_memory_mib` | integer | Specification GPU memory, in MiB. |
| `data.gpu_cores` | integer | Specification GPU core field. |
| `data.min_replicas` | integer | Configured minimum replica field; not the currently observed replica count. |
| `data.max_replicas` | integer | Replica limit for each Worker type, not a combined limit across all types. |
| `data.current_replicas` | integer | Aggregate current instance replica field; separate from per-type observations. |
| `data.desired_replicas` | integer | Target instance replica field; does not indicate readiness. |
| `data.go_worker_image_id` | string | Legacy Go Worker image ID; may be empty. |
| `data.python_worker_image_id` | string | Legacy Python Worker image ID; may be empty. |
| `data.worker_images` | object (array of objects), optional | Optional images selected by Worker type. See the item fields below. |
| `data.platform` | string | Worker platform configuration. |
| `data.auto_suspend_minutes` | integer | Configured automatic suspension delay in minutes; not a duration guarantee for this operation. |
| `data.scale_reason` | string | Most recent scaling or lifecycle reason. |
| `data.is_default` | boolean | Whether this is the default instance; may be false. |
| `data.status` | string | Parent instance state. Current models include IDLE, DEPLOYING, SCALING, ACTIVE, DRAINING, SUSPENDED, TERMINATING, ERROR, and others. Do not conflate this with Worker states. |
| `data.status_message` | string | Status text; may be empty. |
| `data.py_requirements_txt` | string, optional | Optional saved Python dependency text. May be returned when nonempty; not declared in current typed SDK models. |
| `data.py_requirements_sha` | string, optional | Optional saved dependency content hash; not declared in current typed SDK models. |
| `data.py_deps` | object, optional | The DTO declares an optional observation object, but the current converters for these three lifecycle operations do not populate it. Do not rely on this field for installation progress. |
| `data.created_by` | string | Creating principal. |
| `data.allowed_actions` | string (array of strings) | Allowed-action projection. These three lifecycle operations do not construct actions separately; an empty array does not determine administrator eligibility. |
| `data.last_activation_at` | string, optional | Most recent activation time in RFC3339; omitted when unrecorded. |
| `data.last_active_at` | string, optional | Most recent activity time in RFC3339; omitted when unrecorded. |
| `data.created_at` | string | Creation time in RFC3339. |
| `data.updated_at` | string | Update time in RFC3339; not a caller-supplied concurrency version. |

See [Shared objects](compute-runtime-admin-objects.md) for nested images, declared observation objects, and parent/Worker state relationships.
:::::
::::::
:::::::

<span id="错误响应"></span>

## Error responses

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

```json
{"code":"INVALID_PARAMS","msg":"invalid compute resource request","data":null}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Distinguished by failure stage and operation. |
| `msg` | string | Error text; some branches are localized and do not expose unclassified underlying errors. |
| `data` | null | This example uses null; shared authentication error branches may omit it. |

| HTTP / code | Conditions and handling |
| --- | --- |
| 400 / INVALID_PARAMS | Missing authentication Workspace, principal, or resource ID. |
| 403 / ErrForbidden | The authorization boundary rejects administrator eligibility, the current principal, or Workspace access. |
| 503 / ErrServiceUnavailable | Classified shared authorization unavailability; does not apply to every directory failure. |
| 404 / SUSPEND_ADMIN_FAILED | Target instance not found. This branch uses a different machine code from the runtime query's NOT_FOUND. |
| 409 / CANNOT_SUSPEND | The parent instance does not meet the ACTIVE prerequisite. |
| 409 / LIFECYCLE_CONFLICT | Resume/retry CAS against the expected state conflicts with a concurrent change. |
| 409 / RESOURCE_BUSY | Classified lifecycle lease loss or ongoing Cloud teardown. Check the original operation first. |
| 503 / SUSPEND_ADMIN_FAILED | Classified as runtime service not configured. |
| 500 / SUSPEND_ADMIN_FAILED | An unclassified stop, state write, read-back, or directory fact failure. Check the actual state after the error. |

See [Errors and recovery](compute-runtime-admin-errors-recovery.md) for differences between handlers, identities, and recovery stages.
:::::
::::::
:::::::
