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

# Cancel Dream

> Cancel a pending or running Dream.

`POST /api/v1/cloud/dreams/{id}/cancel`

Cancels the specified Dream. Only Dreams with status `pending` or `running` can be canceled. Calling cancel on an already-canceled Dream is idempotent. Returns the updated [Dream object](/cloud-agents/api/dreams/schemas#dream-object).

## Headers

| Header          | Required | Description    |
| --------------- | -------- | -------------- |
| `Authorization` | Yes      | `Bearer <PAT>` |

## Path parameters

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| `id`      | string | Dream ID (`drm_` prefix) |

## Example request

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/cloud/dreams/drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9/cancel' \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "id": "drm_019e86b4a8f070a3b6c5d4e3f2a1b0c9",
  "type": "dream",
  "status": "canceled",
  "inputs": [{ "type": "memory_store", "memory_store_id": "memstore_019e5cdb9c3f71c3b6505eba937a40b4" }],
  "outputs": [],
  "model": { "id": "auto" },
  "instructions": "",
  "session_id": "sess_019e86b4b10578059435632bb357c5ed",
  "usage": { "input_tokens": 0, "output_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0 },
  "error": null,
  "created_at": "2026-06-15T10:00:00Z",
  "ended_at": "2026-06-15T10:01:15Z",
  "archived_at": null
}
```

## Errors

| HTTP | Type                    | Trigger                                                                                                       |
| ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| 400  | `invalid_request_error` | Dream is in `completed` or `failed` (terminal state, cannot cancel). `canceled` is idempotent and returns 200 |
| 401  | `authentication_error`  | Missing or invalid authentication token                                                                       |
| 404  | `not_found_error`       | Dream does not exist                                                                                          |

See [Error Reference](/cloud-agents/api/conventions/errors) for the full error envelope.