> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pause Sandbox

> Pause a running sandbox to temporarily suspend execution using the HopX Control Plane API. Temporarily stop sandbox execution while preserving filesystem and state. Learn how to use POST /v1/sandboxes/:id/pause endpoint to pause sandboxes, free resources, and resume later. Includes request examples and state management.

Pause a running sandbox to temporarily suspend all execution. The sandbox will transition from `running` to `paused` status. You can resume it later to continue where it left off.

## Endpoint

```
POST /v1/sandboxes/:id/pause
```

## Request

### Headers

```
Authorization: Bearer $HOPX_API_KEY
```

### Path Parameters

| Parameter | Type   | Description         |
| --------- | ------ | ------------------- |
| `id`      | string | Sandbox ID to pause |

### Example Request

```bash theme={null}
curl -X POST https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/pause \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

## Response

### Success (200 OK)

```json theme={null}
{
  "id": "sandbox_abc123xyz",
  "status": "paused",
  "request_id": "req_abc123"
}
```

### Response Fields

| Field        | Type   | Description              |
| ------------ | ------ | ------------------------ |
| `id`         | string | Sandbox ID               |
| `status`     | string | New status (`paused`)    |
| `request_id` | string | Request ID for debugging |

## Status Codes

| Code  | Description                 |
| ----- | --------------------------- |
| `200` | Sandbox paused successfully |
| `401` | Authentication required     |
| `404` | Sandbox not found           |

## Errors

### Sandbox Not Found (404)

```json theme={null}
{
  "error": "Sandbox not found",
  "code": "RESOURCE_NOT_FOUND",
  "request_id": "req_abc123"
}
```

**Cause:** The sandbox ID doesn't exist or belongs to another organization.

**Fix:** Verify the sandbox ID is correct. List your sandboxes using `GET /v1/sandboxes` to find valid IDs.

## Important Notes

* **Execution suspended** - All running processes are paused
* **State preserved** - Memory state and files are retained
* **Can be resumed** - Use [Resume Sandbox](/api/control-plane/resume-sandbox) to continue
* **VM Agent API** - VM Agent API endpoints are unavailable while paused

## Use Cases

### Pause Long-Running Task

```bash theme={null}
# Pause a sandbox running a long computation
curl -X POST https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/pause \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

### Temporarily Free Resources

```bash theme={null}
# Pause to free resources temporarily
curl -X POST https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/pause \
  -H "Authorization: Bearer $HOPX_API_KEY"

# ... later, resume ...
curl -X POST https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz/resume \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

## Related

* **SDK**: [sandbox.pause()](/sdk/python/sandbox#pause) - Python SDK method
* [CLI Sandbox Commands](/cli/commands/sandbox) - Manage sandboxes from CLI

## Next Steps

* **[Resume Sandbox](/api/control-plane/resume-sandbox)** - Resume a paused sandbox
* **[Stop Sandbox](/api/control-plane/stop-sandbox)** - Stop instead of pausing
* **[Get Sandbox](/api/control-plane/get-sandbox)** - Check sandbox status