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

# POST /v1/capsules/{id}/pause — Pause a capsule

> POST /v1/capsules/{id}/pause — Snapshot a running capsule's state to disk and release all VM resources. The capsule can be resumed later.

Use this endpoint to pause a running capsule. Wrenn takes a full snapshot — VM state, memory, and filesystem — writes it to disk, then terminates the running Firecracker process and releases all host resources. The capsule persists as stored files and can be restored exactly to this point using the [resume endpoint](/api-reference/capsules/resume).

<Note>
  Pausing a capsule is the right choice when you want to stop incurring compute costs without losing the capsule's in-memory state. Paused capsules consume only storage.
</Note>

## Endpoint

```http theme={null}
POST https://app.wrenn.dev/api/v1/capsules/{id}/pause
```

## Authentication

Pass your API key in the `X-API-Key` header.

```http theme={null}
X-API-Key: wrn_your_key
```

## Path parameters

<ParamField path="id" type="string" required>
  The ID of the capsule to pause (e.g., `cl-abc123`). The capsule must be in `running` status.
</ParamField>

## Response

Returns `200 OK` with the updated capsule object. The `status` field will be `"paused"`.

<ResponseField name="id" type="string" required>
  Unique capsule ID, prefixed with `cl-`.
</ResponseField>

<ResponseField name="status" type="string" required>
  Will be `"paused"` after a successful pause.
</ResponseField>

<ResponseField name="template" type="string" required>
  Name of the template the capsule was created from.
</ResponseField>

<ResponseField name="vcpus" type="integer" required>
  Number of virtual CPUs that were allocated.
</ResponseField>

<ResponseField name="memory_mb" type="integer" required>
  Memory that was allocated, in MiB.
</ResponseField>

<ResponseField name="timeout_sec" type="integer" required>
  Inactivity TTL in seconds.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the capsule was created.
</ResponseField>

<ResponseField name="last_updated" type="string" required>
  ISO 8601 timestamp of when the capsule was paused.
</ResponseField>

### Example response

```json theme={null}
{
  "id": "cl-abc123",
  "status": "paused",
  "template": "base-python",
  "vcpus": 2,
  "memory_mb": 1024,
  "timeout_sec": 300,
  "created_at": "2024-11-01T10:00:00Z",
  "started_at": "2024-11-01T10:00:05Z",
  "last_active_at": "2024-11-01T10:04:30Z",
  "last_updated": "2024-11-01T10:05:00Z"
}
```

## curl

```bash theme={null}
curl --request POST \
  --url https://app.wrenn.dev/api/v1/capsules/cl-abc123/pause \
  --header 'X-API-Key: wrn_your_key'
```

## Python SDK

```python theme={null}
from wrenn import Capsule

capsule = Capsule.connect("cl-abc123")
capsule.pause()
print(capsule.status)  # "paused"
```

## Error responses

| Status             | Description                                                                  |
| ------------------ | ---------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid `X-API-Key`.                                              |
| `404 Not Found`    | No capsule with the given ID exists in your team.                            |
| `409 Conflict`     | The capsule is not in `running` status. Only running capsules can be paused. |