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

# POST /api/v1/tasks/{id}/pause

> Pause a running task at the next checkpoint

## Endpoint

```http theme={null}
POST http://localhost:8080/api/v1/tasks/{id}/pause
```

## Description

Pauses a running task at the **next workflow checkpoint**. The current activity (LLM call, tool, etc.) is allowed to finish, and then the workflow blocks until it is resumed or cancelled.

Use this when you want to temporarily stop long‑running research or supervisor workflows without losing progress.

## Authentication

**Required**: Yes

Include API key in header:

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

## Request

### Headers

| Header         | Required | Description                |
| -------------- | -------- | -------------------------- |
| `X-API-Key`    | Yes      | API authentication key     |
| `Content-Type` | No       | `application/json` if body |
| `traceparent`  | No       | W3C trace context          |

### Path Parameters

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `id`      | string | Yes      | Task ID (Temporal workflow ID) |

### Body Parameters

| Parameter | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `reason`  | string | No       | Optional pause reason note |

### Request Body Example

```json theme={null}
{
  "reason": "Pause while user reviews intermediate results"
}
```

## Response

### 202 Accepted

```json theme={null}
{
  "success": true,
  "message": "Pause signal sent",
  "task_id": "task-123"
}
```

### 404 Not Found

```json theme={null}
{ "error": "Task not found" }
```

### 409 Failed Precondition

Cannot pause task in invalid state:

```json theme={null}
{ "error": "cannot pause completed task" }
```

```json theme={null}
{ "error": "cannot pause failed task" }
```

```json theme={null}
{ "error": "cannot pause cancelled task" }
```

```json theme={null}
{ "error": "cannot pause timed out task" }
```

```json theme={null}
{ "error": "task is already paused" }
```

### 401 / 403

```json theme={null}
{ "error": "Unauthorized" }
```

or

```json theme={null}
{ "error": "Forbidden" }
```

## Notes

* Pause takes effect at well‑defined checkpoints (e.g., **pre\_execution**, **pre\_completion**); it does **not** interrupt in‑flight activities.
* While paused, SSE streams will emit `workflow.pausing` and `workflow.paused` events with a `checkpoint` field.
* Ownership and tenancy are enforced: users can only pause their own tasks.