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

# Cancel an in-flight Knoq session

> POST /api/managed-agents/cancel — stops a running session. The session is marked cancelled and the workflow exits on its next poll cycle.

When you cancel a session, Knoq stamps a cancellation timestamp on the session record. The background workflow checks for this signal on every poll cycle and exits gracefully as soon as it detects it — typically within one poll interval (1–5 seconds). The session and its transcript are preserved; only the in-flight turn is interrupted.

Cancellation is idempotent. If the session is already cancelled (or was never running), the endpoint returns `{ "ok": true }` without error. This makes it safe to call multiple times or from multiple clients without special-casing the response.

<Note>
  Cancelling a session does not delete it. To remove the session and its events permanently, use the [Delete Session](/api-reference/sessions/delete) endpoint.
</Note>

```
POST /api/managed-agents/cancel
```

## Request

<ParamField body="sessionId" type="string" required>
  The ID of the session to cancel. You can obtain this from the [Create Session](/api-reference/sessions/create) response or the [List Sessions](/api-reference/sessions/list) endpoint.
</ParamField>

## Response

<ResponseField name="ok" type="boolean">
  Always `true` when the cancellation request is accepted.
</ResponseField>

<ResponseField name="alreadyCancelled" type="boolean">
  Present and `true` when the session had already been cancelled before this request. The cancellation timestamp was not updated.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://knoq.one/api/managed-agents/cancel \
    -H "Content-Type: application/json" \
    -H "Origin: https://knoq.one" \
    -H "Cookie: <your-session-cookie>" \
    -d '{
      "sessionId": "a3f2c1d4-e5b6-7890-abcd-ef1234567890"
    }'
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

### Idempotent response (already cancelled)

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://knoq.one/api/managed-agents/cancel \
    -H "Content-Type: application/json" \
    -H "Origin: https://knoq.one" \
    -H "Cookie: <your-session-cookie>" \
    -d '{
      "sessionId": "a3f2c1d4-e5b6-7890-abcd-ef1234567890"
    }'
  ```

  ```json Response theme={null}
  {
    "ok": true,
    "alreadyCancelled": true
  }
  ```
</CodeGroup>

## Errors

| Status | Meaning                                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| `400`  | The `sessionId` field is missing, empty, or malformed.                                                            |
| `401`  | The request is not authenticated. Ensure your session cookie is valid and has not expired.                        |
| `404`  | No session with the given ID was found for your user and organisation.                                            |
| `429`  | Cancel burst rate limit exceeded (30 requests per minute per user). The response includes a `Retry-After` header. |