Skip to main content
POST
/
v1
/
workflows
/
runs
/
{run_id}
/
cancel
from retab import Retab

client = Retab()

result = client.workflows.runs.cancel(
    run_id="run_abc123",
    command_id="cmd_cancel_abc",  # optional dedup key
)

print(result.cancellation_status)
print(result.run.lifecycle.status)

{
  "run": {
    "id": "run_abc123",
    "workflow": {
      "workflow_id": "wf_abc123xyz",
      "version_id": "ver_abc123xyz"
    },
    "trigger": { "type": "api" },
    "lifecycle": {
      "status": "cancelled",
      "reason": "user requested cancellation"
    },
    "timing": {
      "created_at": "2026-05-01T14:30:00Z",
      "started_at": "2026-05-01T14:30:00Z",
      "completed_at": "2026-05-01T14:30:08Z"
    },
    "inputs": { "documents": {}, "json_data": {} }
  },
  "cancellation_status": "cancelled"
}
Cancel a running or pending workflow run. Cancellation is delivered through Temporal, so the response can carry one of three states:
  • cancelled — the run reached a cancelled terminal state.
  • cancellation_requested — the cancel signal was accepted; the run will reach cancelled shortly. Re-poll Get Run to observe the transition.
  • cancellation_failed — Temporal rejected the cancel (e.g. the run already finished). The returned run reflects the actual current state.
The optional command_id is an idempotency key — replaying the same value never enqueues a second cancel. 
from retab import Retab

client = Retab()

result = client.workflows.runs.cancel(
    run_id="run_abc123",
    command_id="cmd_cancel_abc",  # optional dedup key
)

print(result.cancellation_status)
print(result.run.lifecycle.status)

{
  "run": {
    "id": "run_abc123",
    "workflow": {
      "workflow_id": "wf_abc123xyz",
      "version_id": "ver_abc123xyz"
    },
    "trigger": { "type": "api" },
    "lifecycle": {
      "status": "cancelled",
      "reason": "user requested cancellation"
    },
    "timing": {
      "created_at": "2026-05-01T14:30:00Z",
      "started_at": "2026-05-01T14:30:00Z",
      "completed_at": "2026-05-01T14:30:08Z"
    },
    "inputs": { "documents": {}, "json_data": {} }
  },
  "cancellation_status": "cancelled"
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required

Body

application/json

Optional request payload for cancel workflow command idempotency.

​
command_id
string | null

Optional idempotency key for deduplicating cancel commands

Response

Successful Response

Response for cancel workflow endpoint.

​
run
WorkflowRun · object
required

A single execution of a workflow.

​
redis_available
boolean
default:true

Whether immediate cancellation signaling was available

​
cancellation_status
enum<string>
default:cancellation_requested

Cancellation delivery state from this request

Available options:
cancelled,
cancellation_requested,
cancellation_failed