# Abort

POST /v1/agents/abort

Stops a running task. Safe to call when nothing is running.

## Request

Recommended for API callers: name the session you started.

```json
{ "sessionId": "cs_01HZY" }
```

Or name the computer and the channel:

```json
{ "machineId": "m_7f2a", "channel": "api" }
```

| Field       | Type   | Required         | Notes                                                                                         |
| ----------- | ------ | ---------------- | --------------------------------------------------------------------------------------------- |
| `sessionId` | string | one of the two   | The `sessionId` from `POST /message` or `GET /events`. Must belong to the caller.             |
| `machineId` | string | one of the two   | Stops the conversation on this computer for the given `channel`.                              |
| `channel`   | string | with `machineId` | `api` or `cli`. Omitted, it stops the `sai` CLI's conversation, not yours. Always send `api`. |

## Response

A task was stopped:

```json
{ "ok": true, "aborted": true }
```

Nothing to stop:

```json
{ "ok": true, "aborted": false, "reason": "session already idle or aborting" }
```

`reason` is `no active session` or `session already idle or aborting`.

## Errors

| Status | Body                                                                   |
| ------ | ---------------------------------------------------------------------- |
| `400`  | Neither `sessionId` nor `machineId` was sent.                          |
| `403`  | `{ "error": "Session not found or does not belong to your account." }` |
| `404`  | `{ "error": "Machine not found or does not belong to your account." }` |
| `429`  | More than 20 aborts in an hour.                                        |

## Gotchas

- Use `sessionId`. It needs no machine lookup, so it also works on a free account's computer between claims.
- With `machineId`, the default channel is `cli`. Forgetting `channel: "api"` reports `no active session` while your task keeps running.
- Pending approvals on the aborted task are resolved as denied, so nothing is left waiting.

> **Note**
>
> `sessionId` and `channel` on `/abort` are available from October 1. Today's staging accepts `machineId` only and stops the CLI's conversation.