Skip to main content
POST
/
v1
/
workflows
/
{workflow_id}
/
run
from retab import Retab
from pathlib import Path

client = Retab()

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

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

{
  "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 input documents. 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. 
from retab import Retab
from pathlib import Path

client = Retab()

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

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

{
  "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.

Documents are provided as a dict mapping start node IDs to document inputs.

Example: { "documents": { "start-node-1": { "filename": "invoice.pdf", "mime_type": "application/pdf", "content": "base64_encoded_content..." }, "start-node-2": { "filename": "receipt.pdf", "mime_type": "application/pdf", "content": "base64_encoded_content..." } } }

​
documents
Documents · object
required

Mapping of start node IDs to their input documents

Response

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
​
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

​
input_documents
Input Documents · object

Start node ID -> input document reference

​
final_outputs
Final Outputs · object

Final outputs from end nodes

​
error
string | null

Error message if workflow failed

​
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