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.kind)

{
  "run": {
    "id": "run_abc123",
    "organization_id": "org_123",
    "workflow": {
      "workflow_id": "wf_abc123xyz",
      "snapshot_id": "snap_abc123",
      "name_at_run_time": "Invoice Processing"
    },
    "trigger": { "type": "api" },
    "lifecycle": { "kind": "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",
      "human_waiting_started_at": null,
      "accumulated_human_waiting_ms": 0,
      "duration_ms": 8000,
      "active_duration_ms": 8000
    },
    "inputs": { "documents": {}, "json_data": {} }
  },
  "cancellation_status": "cancelled"
}

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

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.kind)

{
  "run": {
    "id": "run_abc123",
    "organization_id": "org_123",
    "workflow": {
      "workflow_id": "wf_abc123xyz",
      "snapshot_id": "snap_abc123",
      "name_at_run_time": "Invoice Processing"
    },
    "trigger": { "type": "api" },
    "lifecycle": { "kind": "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",
      "human_waiting_started_at": null,
      "accumulated_human_waiting_ms": 0,
      "duration_ms": 8000,
      "active_duration_ms": 8000
    },
    "inputs": { "documents": {}, "json_data": {} }
  },
  "cancellation_status": "cancelled"
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required

Query Parameters

​
access_token
string | null

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 stored workflow run record.

Slim, typed, discriminated. Engine-only state is segregated into engine and excluded from API serialization (Field(exclude=True)). The terminal state (success/error/cancelled) is encoded in lifecycle, not spread across loose error / error_details / etc. fields.

Steps are NOT embedded — fetch via StepsView(run_id, ...) or the GET /v1/workflows/runs/{run_id}/steps endpoint.

​
redis_available
boolean
default:true

Whether Redis was available to set the cancellation flag for immediate effect

​
cancellation_status
enum<string>
default:cancellation_requested

Cancellation delivery state from this request

Available options:
cancelled,
cancellation_requested,
cancellation_failed