List Blocks

List blocks for a workflow with keyset cursor pagination.

Sorted by updated_at descending with id as the tiebreaker. Pass after (the previous response’s list_metadata.after) for the next page, before for the previous page. They are mutually exclusive; the 400 cleanly tells the caller which to drop.

GET /v1/workflows/blocks

Python

from retab import Retab

client = Retab()

blocks = client.workflows.blocks.list("wf_abc123xyz")

for block in blocks.data:
    print(f"{block.id} ({block.type}): {block.label}")

200

{
  "data": [
    {
      "id": "start-1",
      "workflow_id": "wf_abc123xyz",
      "type": "start_document",
      "label": "Invoice Input",
      "position_x": 0,
      "position_y": 0,
      "width": 240,
      "height": 120,
      "config": null,
      "parent_id": null,
      "updated_at": "2026-04-30T17:00:00Z"
    },
    {
      "id": "extract-1",
      "workflow_id": "wf_abc123xyz",
      "type": "extract",
      "label": "Extract Invoice Fields",
      "position_x": 320,
      "position_y": 0,
      "width": 240,
      "height": 120,
      "config": {
        "model": "gpt-5",
        "json_schema": {
          "type": "object",
          "properties": {
            "invoice_number": { "type": "string" },
            "total": { "type": "number" }
          }
        }
      },
      "parent_id": null,
      "updated_at": "2026-05-01T14:30:00Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

List every authored block in a workflow’s current draft.

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

Use this endpoint with List Edges when you need to reconstruct a workflow graph.

Python

from retab import Retab

client = Retab()

blocks = client.workflows.blocks.list("wf_abc123xyz")

for block in blocks.data:
    print(f"{block.id} ({block.type}): {block.label}")

200

{
  "data": [
    {
      "id": "start-1",
      "workflow_id": "wf_abc123xyz",
      "type": "start_document",
      "label": "Invoice Input",
      "position_x": 0,
      "position_y": 0,
      "width": 240,
      "height": 120,
      "config": null,
      "parent_id": null,
      "updated_at": "2026-04-30T17:00:00Z"
    },
    {
      "id": "extract-1",
      "workflow_id": "wf_abc123xyz",
      "type": "extract",
      "label": "Extract Invoice Fields",
      "position_x": 320,
      "position_y": 0,
      "width": 240,
      "height": 120,
      "config": {
        "model": "gpt-5",
        "json_schema": {
          "type": "object",
          "properties": {
            "invoice_number": { "type": "string" },
            "total": { "type": "number" }
          }
        }
      },
      "parent_id": null,
      "updated_at": "2026-05-01T14:30:00Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

Authorizations

Api-Key · string · header · required

Query Parameters

workflow_id · string · required

before · string | null

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

after · string | null

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

limit · integer · default: 100

Maximum number of blocks to return per page (1-200).

Required range: 1 <= x <= 200

Response

200

application/json

Successful Response

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

data · WorkflowBlock · object[] · required

Show child attributes

list_metadata · ListMetadata · object · required

Boundary resource IDs for page navigation.

Show child attributes