# Cancel a run

POST https://fusara.ai/api/v3/run/{id}/cancel

No request body. Cancels only queued runs that have never been admitted or dispatched. Admission and cancellation are serialized atomically. Running/outcome-unknown work returns 409 run_not_cancelable. Already terminal runs return their current snapshot with 200, including outputs if applicable. Repeating cancellation needs no Idempotency-Key. A newly canceled run releases its commitment and emits its configured terminal webhook once (delivery retries remain possible). Foreign or non-v3 runs return 404.

## Example request

```bash
curl 'https://fusara.ai/api/v3/run/123456/cancel' \
  --request POST \
  -H "Authorization: Bearer $FUSARA_API_KEY"
```

## Parameters

- `id` (integer, required) path; Format: int64; Minimum: 1; Maximum: 4294967295.

## Responses

### 200

OK

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

```json
{
  "id": 123456,
  "status": "canceled",
  "cost": {
    "unit": "common_fuz",
    "expected": "40.0000",
    "status": "settled",
    "charged": "0.0000"
  }
}
```

#### Response body

- `id` (integer, required): Numeric run ID. Use it for status, results, cancellation and matching webhooks. Format: int64; Minimum: 0; Maximum: 4294967295.
- `status` (string, required): queued or running while in progress; succeeded, failed or canceled when terminal.
- `cost` (object, required)
- `cost.unit` (string, required): Billing unit: common_fuz.
- `cost.expected` (string, required): Total accepted estimate for this run, as a decimal string.
- `cost.status` (string, required): pending until billing is confirmed, then settled. Generation can finish before settlement.
- `cost.charged` (string): Confirmed final charge, as a decimal string. Omitted while pending; confirmed zero is 0.0000.
- `outputs` (object[]): Applicable outputs in their original order. Omitted when none exist; a failed run can still have usable partial outputs.
- `outputs.type` (string, required) Alternative values: "text", "json", "boolean", "image", "video", "audio", "media", "model_asset".
- `outputs.media_id` (integer): Reusable account media ID when this output is a file. Format: int64; Minimum: 0; Maximum: 4294967295.
- `outputs.url` (string): Download URL when the file is available. Save it before url_expires_at.
- `outputs.url_expires_at` (string): UTC expiry of this output URL, when provided. Format: date-time.
- `outputs.expired` (boolean): True when the media is no longer available; its dead URL is omitted.
- `outputs.value` (any JSON value): Inline result: a string for type=text, a native JSON value for type=json, or a boolean for type=boolean. Empty strings, false and JSON null are valid values. Omitted for files and model assets. When type is "text": required; string; When type is "json": required; any JSON value; When type is "boolean": required; boolean; When type is "image" or "video" or "audio" or "media" or "model_asset": must be omitted.
- `outputs.model_asset_id` (integer) Format: int64; Minimum: 0; Maximum: 4294967295.
- `error` (object)
- `error.code` (string, required): Machine-readable generation failure code.
- `error.message` (string, required): Human-readable explanation of the generation failure.

### 400

invalid_header: supply only one authentication header, Authorization: Bearer or X-API-Key. invalid_request: cancellation does not accept a request body.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 401

authentication_required: the API key is missing or invalid. Public methods allow omission, but reject invalid supplied credentials.

#### Response headers

- `WWW-Authenticate` (string, required): Bearer authentication challenge. Values: "Bearer".
- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 404

resource_not_found: the run is missing, belongs to another owner or was not accepted through v3.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 409

run_not_cancelable: the run has already been admitted or dispatched. Read its current state; do not retry cancellation automatically. Already terminal runs return 200.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 422

validation_error: correct the fields identified by error.errors[].pointer; unknown fields and query parameters are rejected.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 429

rate_limited (retryable: true): wait for the indicated delay, then retry. Use bounded backoff if no delay is supplied.

#### Response headers

- `Retry-After` (integer): When supplied, the minimum number of seconds to wait before retrying a transient failure. Preserve the original idempotency key and body when retrying a submission. Minimum: 1.
- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 500

internal_error: unexpected server failure. Contact support if the failure persists; inspect error.retryable before retrying automatically.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.