Get Run

from retab import Retab

client = Retab()

run = client.workflows.runs.get("run_abc123xyz")

print(f"Status: {run.status}")
if run.status == "completed":
    print(f"Duration: {run.duration_ms}ms")
    print(f"Outputs: {run.final_outputs}")

{
  "id": "run_abc123xyz",
  "workflow_id": "wf_abc123xyz",
  "workflow_name": "Invoice Processing",
  "organization_id": "org_123",
  "status": "completed",
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:15Z",
  "duration_ms": 15000,
  "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": "completed",
      "started_at": "2024-01-15T10:30:01Z",
      "completed_at": "2024-01-15T10:30:10Z",
      "duration_ms": 9000,
      "output": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    },
    {
      "node_id": "end-node-1",
      "node_type": "end",
      "node_label": "Output",
      "status": "completed",
      "started_at": "2024-01-15T10:30:10Z",
      "completed_at": "2024-01-15T10:30:15Z",
      "duration_ms": 5000
    }
  ],
  "input_documents": {
    "start-node-1": {
      "file_id": "file_123",
      "filename": "invoice.pdf",
      "mime_type": "application/pdf"
    }
  },
  "final_outputs": {
    "end-node-1": {
      "label": "Output",
      "json_data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    }
  },
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:15Z",
  "waiting_for_node_ids": []
}

GET

workflows

runs

{run_id}

from retab import Retab

client = Retab()

run = client.workflows.runs.get("run_abc123xyz")

print(f"Status: {run.status}")
if run.status == "completed":
    print(f"Duration: {run.duration_ms}ms")
    print(f"Outputs: {run.final_outputs}")

{
  "id": "run_abc123xyz",
  "workflow_id": "wf_abc123xyz",
  "workflow_name": "Invoice Processing",
  "organization_id": "org_123",
  "status": "completed",
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:15Z",
  "duration_ms": 15000,
  "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": "completed",
      "started_at": "2024-01-15T10:30:01Z",
      "completed_at": "2024-01-15T10:30:10Z",
      "duration_ms": 9000,
      "output": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    },
    {
      "node_id": "end-node-1",
      "node_type": "end",
      "node_label": "Output",
      "status": "completed",
      "started_at": "2024-01-15T10:30:10Z",
      "completed_at": "2024-01-15T10:30:15Z",
      "duration_ms": 5000
    }
  ],
  "input_documents": {
    "start-node-1": {
      "file_id": "file_123",
      "filename": "invoice.pdf",
      "mime_type": "application/pdf"
    }
  },
  "final_outputs": {
    "end-node-1": {
      "label": "Output",
      "json_data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    }
  },
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:15Z",
  "waiting_for_node_ids": []
}

Get a single workflow run by ID. Use this endpoint to check the status of a running workflow or retrieve the results of a completed workflow.

from retab import Retab

client = Retab()

run = client.workflows.runs.get("run_abc123xyz")

print(f"Status: {run.status}")
if run.status == "completed":
    print(f"Duration: {run.duration_ms}ms")
    print(f"Outputs: {run.final_outputs}")

{
  "id": "run_abc123xyz",
  "workflow_id": "wf_abc123xyz",
  "workflow_name": "Invoice Processing",
  "organization_id": "org_123",
  "status": "completed",
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:15Z",
  "duration_ms": 15000,
  "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": "completed",
      "started_at": "2024-01-15T10:30:01Z",
      "completed_at": "2024-01-15T10:30:10Z",
      "duration_ms": 9000,
      "output": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    },
    {
      "node_id": "end-node-1",
      "node_type": "end",
      "node_label": "Output",
      "status": "completed",
      "started_at": "2024-01-15T10:30:10Z",
      "completed_at": "2024-01-15T10:30:15Z",
      "duration_ms": 5000
    }
  ],
  "input_documents": {
    "start-node-1": {
      "file_id": "file_123",
      "filename": "invoice.pdf",
      "mime_type": "application/pdf"
    }
  },
  "final_outputs": {
    "end-node-1": {
      "label": "Output",
      "json_data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    }
  },
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:15Z",
  "waiting_for_node_ids": []
}

Authorizations

Api-Key

string

header

required

Path Parameters

run_id

string

required

Query Parameters

access_token

string | null

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)

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

execution_phase

enum<string> | null

Dispatch/execution phase: created -> dispatching -> started -> running

Available options:

created,

dispatching,

started,

running

trigger_type

enum<string>

default:manual

How this run was triggered

Available options:

manual,

api,

schedule,

webhook,

email,

restart

trigger_email

string | null

Sender email address when trigger_type is 'email'

started_at

string<date-time>

completed_at

string<date-time> | null

When the workflow completed

duration_ms

integer | null

Total duration in milliseconds

human_waiting_started_at

string<date-time> | null

When the current waiting_for_human period started

human_waiting_duration_ms

integer

default:0

Accumulated time spent waiting for human review across the run

Required range: x >= 0

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,

registry_lookup,

execution,

output_storage,

routing,

history_payload

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

cancel_signal_error

string | null

Latest cancellation signaling error

cancel_signal_failed_at

string<date-time> | null

When cancellation signaling most recently failed

cancel_native_error

string | null

Best-effort native Temporal cancellation error (if any)

cancel_confirmation_error

string | null

Error encountered while confirming cancellation delivery

cancel_confirmation_pending

boolean

default:false

Whether cancellation was requested but not yet confirmed by Temporal status

cancel_requested_at

string<date-time> | null

When cancellation was last requested for this run

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 execution state restoration

executed_node_ids

string[]

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

parallel_completion_counters

Parallel Completion Counters · object

DEPRECATED - Use len(parallel_mr_completed[mr_id]) instead. Was {mr_id: completed_count}

Show child attributes

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

hil_signal_states

Hil Signal States · object

Per-node Temporal HIL signal delivery state

Show child attributes

Run Workflow Create Job

API Reference

Schemas

Documents

Edit

Workflows

Jobs

Projects

Extractions

Authorizations

Path Parameters

Query Parameters

Response