Get Step

Get one step by its step id.

Returns the same step shape as GET /workflows/steps.

GET /v1/workflows/steps/{step_id}

Python

from retab import Retab

client = Retab()

step = client.workflows.steps.get("step_extract_1")

print(step.lifecycle.status)
print(step.handle_outputs)

if step.handle_outputs:
    payload = step.handle_outputs["output-json-0"]
    print(payload.type)
    print(payload.data)

200

{
  "step_id": "step_extract_1",
  "run_id": "run_abc123xyz",
  "block_id": "extract-block-1",
  "block_type": "extract",
  "block_label": "Extract Invoice",
  "lifecycle": { "status": "completed" },
  "started_at": "2026-05-18T10:00:00Z",
  "completed_at": "2026-05-18T10:00:04Z",
  "loop_containers": [],
  "artifact": { "operation": "extraction", "id": "ext_abc123" },
  "retry_count": 0,
  "created_at": "2026-05-18T10:00:00Z",
  "handle_outputs": {
    "output-json-0": {
      "type": "json",
      "data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    }
  },
  "handle_inputs": {
    "input-file-0": {
      "type": "file",
      "document": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    }
  },
  "model": null
}

Get one persisted step object by step_id. The response uses the same step shape as List Steps: lifecycle, handle payloads, artifact ref, and timing fields.

Python

from retab import Retab

client = Retab()

step = client.workflows.steps.get("step_extract_1")

print(step.lifecycle.status)
print(step.handle_outputs)

if step.handle_outputs:
    payload = step.handle_outputs["output-json-0"]
    print(payload.type)
    print(payload.data)

200

{
  "step_id": "step_extract_1",
  "run_id": "run_abc123xyz",
  "block_id": "extract-block-1",
  "block_type": "extract",
  "block_label": "Extract Invoice",
  "lifecycle": { "status": "completed" },
  "started_at": "2026-05-18T10:00:00Z",
  "completed_at": "2026-05-18T10:00:04Z",
  "loop_containers": [],
  "artifact": { "operation": "extraction", "id": "ext_abc123" },
  "retry_count": 0,
  "created_at": "2026-05-18T10:00:00Z",
  "handle_outputs": {
    "output-json-0": {
      "type": "json",
      "data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    }
  },
  "handle_inputs": {
    "input-file-0": {
      "type": "file",
      "document": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    }
  },
  "model": null
}

Authorizations

Api-Key · string · header · required

Path Parameters

step_id · string · required

Query Parameters

run_id · string | null

Optional workflow run ID disambiguator.

Response

200

application/json

Successful Response

Public step status object.

block_id · string · required

Logical ID of the block

step_id · string · required

Full step ID with iteration context. Assigned ONCE at creation, never recomputed.

block_type · enum<string> · required

Type of the block

Available options: start_document, start_json, note, parse, edit, extract, split, classifier, conditional, api_call, function, while_loop, for_each, 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

lifecycle · PendingStepLifecycle · object · required

The step has been created but execution has not started.

PendingStepLifecycle

QueuedStepLifecycle

RunningStepLifecycle

CompletedStepLifecycle

AwaitingReviewStepLifecycle

ErrorStepLifecycle

SkippedStepLifecycle

CancelledStepLifecycle

Show child attributes

run_id · string · required

Parent workflow run ID

started_at · string<date-time> | null

When the step started executing

completed_at · string<date-time> | null

When the step finished executing

model · string | null

LLM model used by this step, when applicable

loop_containers · ContainerContextData · object[]

Container hierarchy from outermost to innermost. Empty when not inside any container.

Show child attributes

created_at · string<date-time> | null

When the step was created

handle_inputs · Handle Inputs · object

Handle input payloads consumed by this step

Show child attributes

handle_outputs · Handle Outputs · object

Handle output payloads produced by this step

Show child attributes

artifact · StepArtifactRef · object

Reference to the result produced by this step, if any.

Show child attributes

retry_count · integer · default: 0

Number of retry attempts