List Steps

from retab import Retab

client = Retab()

steps = client.workflows.runs.steps.list("run_abc123xyz")

for step in steps:
    print(step.node_id, step.status)

[
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "node_id": "extract-node-1",
    "step_id": "extract-node-1",
    "node_type": "extract",
    "node_label": "Extract Invoice",
    "status": "completed",
    "started_at": "2026-03-12T09:00:00Z",
    "completed_at": "2026-03-12T09:00:03Z",
    "duration_ms": 3000,
    "output": {
      "invoice_number": "INV-2024-001",
      "total_amount": 1234.56
    },
    "handle_outputs": {
      "output-json-0": {
        "type": "json",
        "data": {
          "invoice_number": "INV-2024-001",
          "total_amount": 1234.56
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "file_id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "created_at": "2026-03-12T09:00:00Z",
    "updated_at": "2026-03-12T09:00:03Z"
  },
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "node_id": "split-node-1",
    "step_id": "split-node-1",
    "node_type": "split",
    "node_label": "Split Documents",
    "status": "completed",
    "started_at": "2026-03-12T09:00:03Z",
    "completed_at": "2026-03-12T09:00:04Z",
    "duration_ms": 1000,
    "handle_outputs": {
      "output-file-Invoice": {
        "type": "file",
        "document": {
          "file_id": "file_456",
          "filename": "invoice_page_1.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "file_id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "created_at": "2026-03-12T09:00:03Z",
    "updated_at": "2026-03-12T09:00:04Z"
  }
]

GET

workflows

runs

{run_id}

steps

from retab import Retab

client = Retab()

steps = client.workflows.runs.steps.list("run_abc123xyz")

for step in steps:
    print(step.node_id, step.status)

[
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "node_id": "extract-node-1",
    "step_id": "extract-node-1",
    "node_type": "extract",
    "node_label": "Extract Invoice",
    "status": "completed",
    "started_at": "2026-03-12T09:00:00Z",
    "completed_at": "2026-03-12T09:00:03Z",
    "duration_ms": 3000,
    "output": {
      "invoice_number": "INV-2024-001",
      "total_amount": 1234.56
    },
    "handle_outputs": {
      "output-json-0": {
        "type": "json",
        "data": {
          "invoice_number": "INV-2024-001",
          "total_amount": 1234.56
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "file_id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "created_at": "2026-03-12T09:00:00Z",
    "updated_at": "2026-03-12T09:00:03Z"
  },
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "node_id": "split-node-1",
    "step_id": "split-node-1",
    "node_type": "split",
    "node_label": "Split Documents",
    "status": "completed",
    "started_at": "2026-03-12T09:00:03Z",
    "completed_at": "2026-03-12T09:00:04Z",
    "duration_ms": 1000,
    "handle_outputs": {
      "output-file-Invoice": {
        "type": "file",
        "document": {
          "file_id": "file_456",
          "filename": "invoice_page_1.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "file_id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "created_at": "2026-03-12T09:00:03Z",
    "updated_at": "2026-03-12T09:00:04Z"
  }
]

Retrieve the full persisted step list for a workflow run. Use this when you want the complete set of step documents for a run, including statuses, outputs, handle inputs/outputs, and loop metadata.

from retab import Retab

client = Retab()

steps = client.workflows.runs.steps.list("run_abc123xyz")

for step in steps:
    print(step.node_id, step.status)

[
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "node_id": "extract-node-1",
    "step_id": "extract-node-1",
    "node_type": "extract",
    "node_label": "Extract Invoice",
    "status": "completed",
    "started_at": "2026-03-12T09:00:00Z",
    "completed_at": "2026-03-12T09:00:03Z",
    "duration_ms": 3000,
    "output": {
      "invoice_number": "INV-2024-001",
      "total_amount": 1234.56
    },
    "handle_outputs": {
      "output-json-0": {
        "type": "json",
        "data": {
          "invoice_number": "INV-2024-001",
          "total_amount": 1234.56
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "file_id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "created_at": "2026-03-12T09:00:00Z",
    "updated_at": "2026-03-12T09:00:03Z"
  },
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "node_id": "split-node-1",
    "step_id": "split-node-1",
    "node_type": "split",
    "node_label": "Split Documents",
    "status": "completed",
    "started_at": "2026-03-12T09:00:03Z",
    "completed_at": "2026-03-12T09:00:04Z",
    "duration_ms": 1000,
    "handle_outputs": {
      "output-file-Invoice": {
        "type": "file",
        "document": {
          "file_id": "file_456",
          "filename": "invoice_page_1.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "file_id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "created_at": "2026-03-12T09:00:03Z",
    "updated_at": "2026-03-12T09:00:04Z"
  }
]

Authorizations

Api-Key

string

header

required

Path Parameters

run_id

string

required

Query Parameters

access_token

string | null

Response

Successful Response

node_id

string

required

Logical ID of the node (e.g., 'extract-123')

node_type

enum<string>

required

Type of the node

Available options:

start,

start_json,

end,

note,

parse,

edit,

extract,

split,

classifier,

conditional,

hil,

api_call,

functions,

reshape,

while_loop,

for_each,

merge_pdf,

merge_dicts,

while_loop_sentinel_start,

while_loop_sentinel_end,

for_each_sentinel_start,

for_each_sentinel_end

node_label

string

required

Label of the node

status

enum<string>

required

Current status

Available options:

pending,

queued,

running,

completed,

skipped,

error,

waiting_for_human,

cancelled

run_id

string

default:""

Parent workflow run ID

organization_id

string

default:""

Organization that owns this

step_id

string

default:""

Full step ID with iteration context (e.g., 'mr1_iter_0_extract-123'). Assigned once at creation, never recomputed.

started_at

string<date-time> | null

When the step started

completed_at

string<date-time> | null

When the step completed

duration_ms

integer | null

Duration in milliseconds

error

string | null

Error message if failed

error_stage

enum<string> | null

Which execution stage failed

Available options:

input_collection,

registry_lookup,

document_fetch,

execution,

output_storage,

routing,

history_payload

error_category

enum<string> | null

Category of error for retry decisions

Available options:

transient,

permanent,

quota

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

model

string | null

LLM model used (e.g., 'gpt-5.4')

cost

CostBreakdown · object

Cost breakdown for this step

Show child attributes

tokens

TokenUsage · object

Token usage for this step

Show child attributes

trace_spans

TraceSpan · object[] | null

Nested execution trace spans

Show child attributes

output

Output · object

Output data from the step

handle_outputs

Handle Outputs · object

Output payloads keyed by handle ID (e.g., 'output-file-0', 'output-json-0', 'output-file-SubdocumentName')

Show child attributes

handle_inputs

Handle Inputs · object

Input payloads keyed by handle ID (e.g., 'input-file-0', 'input-json-0'). Captures what this node received.

Show child attributes

input_document

BaseMIMEData · object

Reference to input document

Show child attributes

output_document

BaseMIMEData · object

Reference to output document

Show child attributes

split_documents

Split Documents · object

For split nodes: subdocument -> document reference

Show child attributes

requires_human_review

boolean | null

Whether this step requires human review

human_reviewed_at

string<date-time> | null

When human review was completed

human_review_approved

boolean | null

Whether human approved or rejected

retry_count

integer | null

Number of retry attempts for this step execution

loop_id

string | null

ID of the containing while_loop (if inside a loop)

iteration

integer | null

Iteration number (0-based) if inside a loop

iteration_context

IterationContextData · object

Structured container hierarchy for this step

Show child attributes

created_at

string<date-time> | null

When the step document was created

updated_at

string<date-time> | null

When the step document was last updated

Get Run Get Step

API Reference

Files

Schemas

Documents

Edit

Workflows

Jobs

Projects

Extractions

Authorizations

Path Parameters

Query Parameters

Response