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

# Cancel Task

> Cancel a running or pending workflow task

## Endpoint

```
POST /v2/tasks/{task_id}/cancel
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `tasks:write`

<Info>
  The cancellation is performed as the access token's user and recorded against them.
</Info>

## Path Parameters

| Parameter | Type    | Required | Description                              |
| --------- | ------- | -------- | ---------------------------------------- |
| `task_id` | integer | Yes      | Unique identifier for the task to cancel |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.chamelio.ai/v2/tasks/12345/cancel" \
    -H "Authorization: Bearer your_access_token"
  ```

  ```python Python theme={null}
  import requests

  task_id = 12345

  url = f"https://platform.chamelio.ai/v2/tasks/{task_id}/cancel"
  headers = {
      "Authorization": "Bearer your_access_token"
  }

  response = requests.post(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const taskId = 12345;

  const response = await fetch(
    `https://platform.chamelio.ai/v2/tasks/${taskId}/cancel`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your_access_token'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "task_id": 12345,
  "status": "cancelled",
  "message": "Task cancelled successfully"
}
```

### Response Fields

| Field     | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `task_id` | integer | ID of the cancelled task                      |
| `status`  | string  | Updated task status (should be `"cancelled"`) |
| `message` | string  | Success confirmation message                  |

## Error Responses

### 400 Bad Request

Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.

```json theme={null}
{
  "detail": "client_credentials tokens are not associated with a user"
}
```

### 401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token lacks the required scope:

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: tasks:write"
}
```

Or when the user may not act on this task:

```json theme={null}
{
  "detail": "You do not have access to this resource"
}
```

### 404 Not Found

Returned when the task does not exist.

```json theme={null}
{
  "detail": "Not found"
}
```

### 409 Conflict

Returned when the task cannot be cancelled - for example it has already completed or been cancelled.

```json theme={null}
{
  "detail": "The task is not in a state that allows this operation"
}
```

### 429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 500 Internal Server Error

Returned when cancellation fails due to a server error.

```json theme={null}
{
  "detail": "Failed to cancel task"
}
```

## Notes

<Warning>
  Cancelling a task is irreversible. The workflow will stop at its current step and cannot be resumed.
</Warning>

<Info>
  Only tasks with status `pending` or `in_progress` can be cancelled. Completed, failed, or already
  cancelled tasks cannot be cancelled.
</Info>

## Use Cases

This endpoint is useful for:

* **User-initiated cancellation** - Let a user stop a workflow they no longer need, as themselves
* **Error handling** - Cancel workflows that are stuck or encountering issues
* **Workflow management** - Clean up unnecessary or duplicate workflow instances