Get Run

Get a single workflow run by ID.

GET /v1/workflows/runs/{run_id}

python

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}")

200

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

python

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}")

200

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

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