List Steps

List steps with status and artifact summaries.

Sorted by started_at ascending with step_id as the tiebreaker (the same compound key the underlying index uses). Pass after for the next page, before for the previous page — mutually exclusive. run_id is optional; when omitted the list is scoped to the caller’s organization.

GET /v1/workflows/steps

Python

from retab import Retab

client = Retab()

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

for step in steps.data:
    print(step.block_id, step.lifecycle.status, step.artifact)

200

{
  "data": [
    {
      "run_id": "run_abc123xyz",
      "block_id": "extract-block-1",
      "step_id": "extract-block-1",
      "block_type": "extract",
      "block_label": "Extract Invoice",
      "lifecycle": { "status": "completed" },
      "artifact": { "operation": "extraction", "id": "ext_abc123" },
      "started_at": "2026-03-12T09:00:00Z",
      "completed_at": "2026-03-12T09:00:03Z",
      "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"
    },
    {
      "run_id": "run_abc123xyz",
      "block_id": "split-block-1",
      "step_id": "split-block-1",
      "block_type": "split",
      "block_label": "Split Documents",
      "lifecycle": { "status": "completed" },
      "artifact": { "operation": "split", "id": "spl_def456" },
      "started_at": "2026-03-12T09:00:03Z",
      "completed_at": "2026-03-12T09:00:04Z",
      "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"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

Retrieve persisted workflow step documents. Pass run_id when you want the complete set of steps for one run, or combine filters such as block_id, step_id, block_type, and status to inspect a narrower set.

Returns the canonical { "data": [...], "list_metadata": { "before": null, "after": null } } pagination envelope shared with all Retab list endpoints. Cursor pagination is not yet implemented for this endpoint — list_metadata is always { before: null, after: null }. When run_id is omitted, the response is organization-scoped and bounded by limit with a default of 200 rows.

Steps include an artifact ref when the block produced a persisted record. Use List Artifacts with step_id to dereference one ref, or with run_id to fetch all artifact records for the run.

Python

from retab import Retab

client = Retab()

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

for step in steps.data:
    print(step.block_id, step.lifecycle.status, step.artifact)

200

{
  "data": [
    {
      "run_id": "run_abc123xyz",
      "block_id": "extract-block-1",
      "step_id": "extract-block-1",
      "block_type": "extract",
      "block_label": "Extract Invoice",
      "lifecycle": { "status": "completed" },
      "artifact": { "operation": "extraction", "id": "ext_abc123" },
      "started_at": "2026-03-12T09:00:00Z",
      "completed_at": "2026-03-12T09:00:03Z",
      "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"
    },
    {
      "run_id": "run_abc123xyz",
      "block_id": "split-block-1",
      "step_id": "split-block-1",
      "block_type": "split",
      "block_label": "Split Documents",
      "lifecycle": { "status": "completed" },
      "artifact": { "operation": "split", "id": "spl_def456" },
      "started_at": "2026-03-12T09:00:03Z",
      "completed_at": "2026-03-12T09:00:04Z",
      "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"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

Authorizations

Api-Key · string · header · required

Query Parameters

run_id · string | null

Optional workflow run ID filter.

block_id · string | null

Optional logical block ID filter.

step_id · string | null

Optional step ID filter.

block_type · string[] | null

Optional block type filter. Repeat the query parameter for multiple values.

status · string[] | null

Optional step lifecycle status filter. Repeat the query parameter for multiple values.

before · string | null

Step id cursor: return the page before this id (mutually exclusive with after).

after · string | null

Step id cursor: return the page after this id (mutually exclusive with before).

limit · integer · default: 20

Maximum number of steps to return per page (1-1000). Each step hydrates its handle payloads from the artifact store, so raise it deliberately for larger pages and use cursor pagination for the rest.

Required range: 1 <= x <= 1000

Response

200

application/json

Successful Response

A page of WorkflowStep resources. data holds the items and list_metadata carries the before/after cursors; pass after to fetch the next page.

data · WorkflowStep · object[] · required

Show child attributes

list_metadata · ListMetadata · object · required

Boundary resource IDs for page navigation.

Show child attributes