Run Workflow

Run a workflow with the provided input documents.

This endpoint creates a workflow run and starts execution in the background:

1. Loading the workflow’s published configuration
2. Validating that all start nodes have corresponding input documents
3. Creating the run record and returning immediately
4. Executing nodes in topological order in the background

Note: Only published workflows can be run. Use POST //publish to publish first.

Args: workflow_id: The ID of the workflow to run request: The run request containing input documents for each start node

Returns: WorkflowRun with status “running” - check the run details endpoint for updates

POST /v1/workflows/{workflow_id}/run

python

from retab import Retab
from pathlib import Path

client = Retab()

# Run with documents only
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start-node-1": Path("invoice.pdf"),
    }
)

# Run with documents and JSON inputs
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start-node-1": Path("invoice.pdf"),
    },
    json_inputs={
        "json-node-1": {"customer_id": "cust_123", "priority": "high"},
    }
)

# Run with all input types
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start-node-1": Path("invoice.pdf"),
    },
    json_inputs={
        "json-node-1": {"customer_id": "cust_123"},
    },
    text_inputs={
        "text-node-1": "Process this invoice urgently",
    }
)

print(f"Run started: {run.id}")
print(f"Status: {run.status}")

200

{
  "id": "run_abc123xyz",
  "workflow_id": "wf_abc123xyz",
  "workflow_name": "Invoice Processing",
  "organization_id": "org_123",
  "status": "running",
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "duration_ms": null,
  "steps": [
    {
      "node_id": "start-node-1",
      "node_type": "start",
      "node_label": "Invoice Input",
      "status": "completed",
      "started_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:01Z",
      "duration_ms": 1000
    },
    {
      "node_id": "extract-node-1",
      "node_type": "extract",
      "node_label": "Extract Data",
      "status": "running",
      "started_at": "2024-01-15T10:30:01Z"
    }
  ],
  "input_documents": {
    "start-node-1": {
      "file_id": "file_123",
      "filename": "invoice.pdf",
      "mime_type": "application/pdf"
    }
  },
  "final_outputs": null,
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:01Z",
  "waiting_for_node_ids": []
}

Run a workflow with the provided inputs. This endpoint creates a workflow run and starts execution in the background. The response returns immediately with status “running” - use the Get Run endpoint to check for updates.

Workflows can accept three types of inputs:

• documents: File inputs for Document (start) nodes
• json_inputs: JSON data for JSON Input (start_json) nodes
• text_inputs: Text strings for Text Input (start_text) nodes

python

from retab import Retab
from pathlib import Path

client = Retab()

# Run with documents only
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start-node-1": Path("invoice.pdf"),
    }
)

# Run with documents and JSON inputs
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start-node-1": Path("invoice.pdf"),
    },
    json_inputs={
        "json-node-1": {"customer_id": "cust_123", "priority": "high"},
    }
)

# Run with all input types
run = client.workflows.runs.create(
    workflow_id="wf_abc123xyz",
    documents={
        "start-node-1": Path("invoice.pdf"),
    },
    json_inputs={
        "json-node-1": {"customer_id": "cust_123"},
    },
    text_inputs={
        "text-node-1": "Process this invoice urgently",
    }
)

print(f"Run started: {run.id}")
print(f"Status: {run.status}")

200

{
  "id": "run_abc123xyz",
  "workflow_id": "wf_abc123xyz",
  "workflow_name": "Invoice Processing",
  "organization_id": "org_123",
  "status": "running",
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "duration_ms": null,
  "steps": [
    {
      "node_id": "start-node-1",
      "node_type": "start",
      "node_label": "Invoice Input",
      "status": "completed",
      "started_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:01Z",
      "duration_ms": 1000
    },
    {
      "node_id": "extract-node-1",
      "node_type": "extract",
      "node_label": "Extract Data",
      "status": "running",
      "started_at": "2024-01-15T10:30:01Z"
    }
  ],
  "input_documents": {
    "start-node-1": {
      "file_id": "file_123",
      "filename": "invoice.pdf",
      "mime_type": "application/pdf"
    }
  },
  "final_outputs": null,
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:01Z",
  "waiting_for_node_ids": []
}

Authorizations

Api-Key · string · header · required

Path Parameters

workflow_id · string · required

Query Parameters

access_token · string | null

Body

application/json

Request to run a workflow with input documents, JSON data, and/or text.

Documents are provided as a dict mapping start node IDs to document inputs. JSON inputs are provided as a dict mapping start_json node IDs to JSON data. Text inputs are provided as a dict mapping start_text node IDs to text strings.

Example: { "documents": { "start-node-1": { "filename": "invoice.pdf", "mime_type": "application/pdf", "content": "base64_encoded_content..." } }, "json_inputs": { "start-json-node-1": { "customer_name": "John Doe", "invoice_number": "INV-001" } }, "text_inputs": { "start-text-node-1": "Some plain text input..." } }

documents · Documents · object

Mapping of start node IDs to their input documents

Show child attributes

json_inputs · Json Inputs · object

Mapping of start_json node IDs to their input JSON data

Show child attributes

text_inputs · Text Inputs · object

Mapping of start_text node IDs to their input text

Show child attributes

Response

200

application/json

Successful Response

A stored workflow run record.

Lightweight document storing:

• Run metadata and status
• Step summaries (full step data in workflow_run_steps collection)
• Reference to config snapshot (stored in separate collection)

workflow_id · string · required

ID of the workflow that was run

workflow_name · string · required

Name of the workflow at time of execution

organization_id · string · required

Organization that owns this run

config_snapshot_id · string · required

Reference to config snapshot (workflow_config_snapshots or workflow_snapshots collection)

id · string

Unique ID for this run

dataset_id · string | null

Optional dataset this run belongs to (for manual runs)

status · enum<string> · default: pending

Overall status

Available options: pending, queued, running, completed, error, waiting_for_human, cancelled

trigger_type · enum<string> · default: manual

How this run was triggered

Available options: manual, api, schedule, webhook

started_at · string<date-time>

completed_at · string<date-time> | null

When the workflow completed

duration_ms · integer | null

Total duration in milliseconds

steps · StepStatusSummary · object[]

Summary status of each step

Show child attributes

input_documents · Input Documents · object

Start node ID -> input document reference

Show child attributes

input_json_data · Input Json Data · object

Start_json node ID -> input JSON data

Show child attributes

input_text_data · Input Text Data · object

Start_text node ID -> input text

Show child attributes

final_outputs · Final Outputs · object

Final outputs from end nodes

error · string | null

Error message if workflow failed

error_stage · enum<string> | null

Which execution stage failed at workflow level

Available options: input_collection, execution, output_storage, routing

error_details · ErrorDetails · object

Detailed error information for debugging.

Captures stack traces and context about where and why an error occurred.

ErrorDetails

Error Details

Show child attributes

cost_summary · RunCostSummary · object

Aggregate cost summary for the entire run

Show child attributes

trace_spans · TraceSpan · object[] | null

Hierarchical execution trace spans

Show child attributes

created_at · string<date-time>

updated_at · string<date-time>

waiting_for_node_ids · string[]

Node IDs that are waiting for human review

pending_node_outputs · Pending Node Outputs · object

Serialized node outputs to resume from

dag_snapshot · Dag Snapshot · object

Serialized DAGSnapshot for Cloud Task state restoration

executed_node_ids · string[]

Node IDs that have completed execution (uses $addToSet for atomic deduplication)

resume_queue · ResumeQueueItem · object[]

Queue of pending resume requests (processed sequentially to prevent race conditions)

Show child attributes

active_resume · ActiveResume · object

Currently processing resume (only one at a time per workflow run)

Show child attributes

run_resume_status · enum<string> · default: idle

High-level status of HIL resume processing

Available options: idle, waiting_for_human, partially_resumed, resuming, fully_resumed