---
title: Cancel Run
description: Stop an in-flight run. Cancelled runs reach a terminal state and are never charged.
source: https://www.edgaze.ai/docs/api/cancel-run
section: api
---
# Cancel Run

> Stop an in-flight run. Cancelled runs reach a terminal state and are never charged.

```apibar
cancel-run
```

## Overview

**Audience: Developers stopping work a buyer no longer wants.**

Requests cancellation of a run that has not reached a terminal state. The run is marked `cancelled` before the call returns, a `run.cancelled` webhook is dispatched, and any subsequent poll of [Get Run](/docs/api/get-run) reports the terminal status.

Cancelled runs are not charged. Any wallet hold is released and `billingStatus` settles to `not_charged`. Edgaze absorbs compute already spent, so cancelling is always safe for the buyer.

Cancellation requires `run:execute` rather than `run:read`, because it changes a run's outcome and its billing.

```doccallout
{"variant":"info","text":"The call is idempotent. Cancelling a run that already completed, failed, or was cancelled returns 200 with cancelRequested false and the existing status."}
```

## Authorization

```apiscopes
cancel-run
```

## Parameters

```apiparams
cancel-run
```

## Response

Example payloads are in the request/response panel above.

`cancelRequested` distinguishes the two success cases: `true` means this call stopped the run, `false` means the run was already terminal and nothing changed.

## Edge cases

```apiedges
cancel-run
```

---

## Endpoint reference
- **Method:** `POST`
- **Path:** `https://api.edgaze.ai/v1/runs/{run_id}/cancel`
- **Scopes:** `run:execute`
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | Bearer token with run:execute scope. |
| `run_id` | path | string | yes | UUID returned from POST /runs. |
## Example responses

### 200 Cancelled
```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "cancelled",
  "cancelRequested": true
}
```

### 200 Already finished

Cancelling a terminal run is a no-op and reports the existing status.

```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "completed",
  "cancelRequested": false
}
```

### 404 Not found
```json
{
  "error": {
    "code": "not_found",
    "message": "Run not found."
  }
}
```

## Edge cases

### Requires run:execute

Cancelling changes a run's outcome and its billing, so it needs run:execute rather than run:read.

### Idempotent

A run that already completed, failed, or was cancelled returns 200 with cancelRequested false and its status unchanged.

### Cancellation is asynchronous at the worker

The run is marked cancelled immediately, but an in-flight node may take a moment to unwind. Any output it had already produced stays in the event log.

### Cross-tenant isolation

Cancelling another account's run returns 404, not 403.