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

client = Retab()

new_run = client.workflows.runs.restart(
    run_id="run_abc123",
    command_id="cmd_restart_abc",  # optional dedup key
)

print(new_run.id)        # new run ID
print(new_run.lifecycle.kind)    # "running"

{
  "id": "run_xyz999",
  "organization_id": "org_123",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "snapshot_id": "snap_xyz999",
    "name_at_run_time": "Invoice Processing"
  },
  "trigger": { "type": "restart", "source_run_id": "run_abc123" },
  "lifecycle": { "kind": "running" },
  "timing": {
    "created_at": "2026-05-01T14:30:00Z",
    "started_at": "2026-05-01T14:30:00Z",
    "completed_at": null,
    "human_waiting_started_at": null,
    "accumulated_human_waiting_ms": 0,
    "duration_ms": null,
    "active_duration_ms": null
  },
  "inputs": {
    "documents": {
      "start-1": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    },
    "json_data": {}
  }
}

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.

Restart a completed, errored, or cancelled run with the same inputs. A brand-new run is created with lifecycle.kind set to running; the original run is left untouched. The restart picks up the current published snapshot — not the snapshot the original run executed against. If you’ve published changes since the original run, the restart reflects them. command_id is an optional idempotency key — replaying the same value never enqueues a second restart. 
from retab import Retab

client = Retab()

new_run = client.workflows.runs.restart(
    run_id="run_abc123",
    command_id="cmd_restart_abc",  # optional dedup key
)

print(new_run.id)        # new run ID
print(new_run.lifecycle.kind)    # "running"

{
  "id": "run_xyz999",
  "organization_id": "org_123",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "snapshot_id": "snap_xyz999",
    "name_at_run_time": "Invoice Processing"
  },
  "trigger": { "type": "restart", "source_run_id": "run_abc123" },
  "lifecycle": { "kind": "running" },
  "timing": {
    "created_at": "2026-05-01T14:30:00Z",
    "started_at": "2026-05-01T14:30:00Z",
    "completed_at": null,
    "human_waiting_started_at": null,
    "accumulated_human_waiting_ms": 0,
    "duration_ms": null,
    "active_duration_ms": null
  },
  "inputs": {
    "documents": {
      "start-1": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    },
    "json_data": {}
  }
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
run_id
string
required

Query Parameters

​
access_token
string | null

Body

application/json

Request payload for restart workflow behavior and idempotency.

​
config_source
enum<string>
required

Config source for the restarted run.

Available options:
draft,
published
​
command_id
string | null

Optional idempotency key for deduplicating restart commands

Response

Successful Response

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.

​
organization_id
string
required

Organization that owns this run

​
workflow
WorkflowSnapshotRef · object
required

Workflow + snapshot reference

​
trigger
ManualTrigger · object
required

Manual run started by a user from the dashboard.

​
id
string

Unique ID for this run

​
lifecycle
PendingRun · object

The run has been created but execution has not started.

​
timing
RunTiming · object

All timing information

​
inputs
RunInputs · object

Input payloads supplied at run creation time