Runs

Cancel Run

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

curl --fail-with-body --silent --show-error -X POST 'https://api.edgaze.ai/v1/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7/cancel' \
  -H "Authorization: Bearer $EDGAZE_API_KEY"

Audience

Developers stopping work a buyer no longer wants.

POSThttps://api.edgaze.ai/v1/runs/{run_id}/cancel

Overview#

Requests cancellation of a run that has not reached a terminal state. Cancellation is asynchronous for a run that has already started: the call records the request and returns, and the run reaches cancelled shortly afterwards. A run that has not started yet (still waiting for capacity or being prepared) is cancelled before the call returns.

To confirm the outcome, poll Get Run until it reports a terminal status, wait for the run.cancelled webhook, or watch the run's stream for its terminal event. A run that finishes before the cancellation takes effect keeps its real outcome.

Cancelled runs are not charged, and billingStatus settles to not_charged.

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

The call is idempotent. Cancelling a run that already completed, failed, or was cancelled returns 200 with cancelRequested false and the existing status. A cancelled run appears as cancelled in GET /runs, GET /runs?status=cancelled, and GET /runs/{id}.

Authorization#

run:execute

Parameters#

Headers

Authorizationstringheaderrequired

Bearer token with run:execute scope.

Example: Bearer edgaze_sk_live_…

Path parameters

run_idstringpathrequired

UUID returned from POST /runs.

Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Response#

Example payloads are in the request/response panel above.

cancelRequested distinguishes the success cases:

true with status: "cancelled": the run had not started and is now cancelled.
true with a non-terminal status such as running: cancellation was requested and is in progress. Poll GET /runs/{id} or wait for the run.cancelled webhook for the terminal state.
false: the run was already terminal (or finished while the request was made) and nothing changed. status is its real outcome.

A 503 cancel_unavailable response means the cancellation could not be delivered. It is safe to retry the same call shortly.

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

cancelRequested true with a non-terminal status means cancellation was requested, not finished. An in-flight step may take a moment to stop, and a run that finishes first keeps its real outcome. Output produced before cancellation remains available in run events.

Cancellation unavailable503cancel_unavailable

If the cancellation cannot be delivered, the call returns 503 cancel_unavailable. Retry the same call shortly.

Cross-tenant isolation

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

Was this useful?

Your response helps us improve the documentation.