Skip to main content
GET
/
v1
/
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.block_id, step.status)

[
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "block_id": "extract-block-1",
    "step_id": "extract-block-1",
    "block_type": "extract",
    "block_label": "Extract Invoice",
    "status": "completed",
    "error": null,
    "artifact": { "operation": "extraction", "id": "ext_abc123" },
    "started_at": "2026-03-12T09:00:00Z",
    "completed_at": "2026-03-12T09:00:03Z",
    "duration_ms": 3000,
    "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": {
          "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",
    "block_id": "split-block-1",
    "step_id": "split-block-1",
    "block_type": "split",
    "block_label": "Split Documents",
    "status": "completed",
    "error": null,
    "artifact": { "operation": "split", "id": "spl_def456" },
    "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": {
          "id": "file_456",
          "filename": "invoice_page_1.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "created_at": "2026-03-12T09:00:03Z",
    "updated_at": "2026-03-12T09:00:04Z"
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

Retrieve the persisted step list for a workflow run. Use this when you want the complete set of step documents for a run, including statuses, 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.block_id, step.status)

[
  {
    "run_id": "run_abc123xyz",
    "organization_id": "org_123",
    "block_id": "extract-block-1",
    "step_id": "extract-block-1",
    "block_type": "extract",
    "block_label": "Extract Invoice",
    "status": "completed",
    "error": null,
    "artifact": { "operation": "extraction", "id": "ext_abc123" },
    "started_at": "2026-03-12T09:00:00Z",
    "completed_at": "2026-03-12T09:00:03Z",
    "duration_ms": 3000,
    "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": {
          "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",
    "block_id": "split-block-1",
    "step_id": "split-block-1",
    "block_type": "split",
    "block_label": "Split Documents",
    "status": "completed",
    "error": null,
    "artifact": { "operation": "split", "id": "spl_def456" },
    "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": {
          "id": "file_456",
          "filename": "invoice_page_1.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "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

​
block_id
string
required

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

​
step_id
string
required

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

​
block_type
enum<string>
required

Type of the block

Available options:
start,
start_json,
end,
note,
parse,
edit,
extract,
split,
classifier,
conditional,
hil,
api_call,
formula,
function,
while_loop,
for_each,
merge_pdf,
merge_dicts,
while_loop_sentinel_start,
while_loop_sentinel_end,
for_each_sentinel_start,
for_each_sentinel_end
​
block_label
string
required

Label of the block

​
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

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

​
model
string | null

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

​
cost
CostBreakdown · object

Cost breakdown for this step

​
tokens
TokenUsage · object

Token usage for this step

​
trace_spans
TraceSpan · object[] | null

Nested execution trace spans

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

​
handle_inputs
Handle Inputs · object

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

​
artifact
StepArtifactRef · object

Canonical persisted resource produced by this step, if any

​
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

​
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