# Cancel a run

> Stop a queued or running run.

`POST https://api.agent.clatterlabs.xyz/v1/runs/{id}/cancel` (key permission: `runs:write`)

Stops a queued or running run at its next step, along with any sub-agents it started.

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): The Account ID that owns the key, like `CL-7K2M9QXA`. Find it in Console › Settings. A missing value answers `401 missing_account_id`; someone else's answers `401 account_mismatch`.

## Path parameters

- `id` (string, required): The run id.

## Response

- `id` (string): The run id (UUID).
- `object` (string): Always `run`.
- `status` (enum<string>): `queued`, `running`, `completed`, `failed` or `cancelled`.
- `title` (string): The run's title.
- `input` (string): Your instructions (first 4,000 characters).
- `output` (string | null): Cosmos's final answer once `completed`, otherwise `null`.
- `error` (object | null): When `failed`: `{ code, message }`, code `out_of_credits` or `run_failed`.
- `files` (object[]): Files the run saved as outputs: `{ name, bytes }`, plus `content` with `?include=files`.
- `steps` (integer): How many steps the agent took.
- `tier` (string): The tier you asked for: `auto`, `flash`, `max` or `heavy`.
- `usage` (object): `{ tokens }` used by the run.
- `metadata` (object | null): Your `metadata`, returned as-is.
- `key_id` (string): The API key that created the run.
- `created_at / updated_at` (string): ISO 8601 timestamps.

## Example request

```bash
curl -X POST "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

## Example response

```json
{
  "id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
  "object": "run",
  "status": "cancelled",
  "title": "Hello from the API",
  "input": "Write hello.py that prints the date, run it, and tell me the output.",
  "output": null,
  "error": null,
  "files": [
    {
      "name": "hello.py",
      "bytes": 61
    }
  ],
  "steps": 4,
  "tier": "auto",
  "usage": {
    "tokens": 18342
  },
  "metadata": {
    "ticket": "OPS-112"
  },
  "key_id": "key_7f3a…",
  "created_at": "2026-10-27T18:40:02.114Z",
  "updated_at": "2026-10-27T18:40:31.870Z"
}
```