Skip to main content
POST
/
v1
/
workflows
/
steps
/
query
from retab import Retab
from retab.types.workflows import StepsQueryRequest

client = Retab()

steps = client.workflows.steps.query(
    StepsQueryRequest(
        workflow_id="wf_abc123",
        block_type="extract",
        status=["completed"],
        limit=20,
    )
)

for step in steps:
    print(step.step_id, step.status, step.fingerprint)

[
  {
    "step_id": "step_abc123",
    "run_id": "run_abc123",
    "workflow_id": "wf_abc123",
    "block_id": "extract-1",
    "block_type": "extract",
    "status": "completed",
    "started_at": "2026-05-21T10:00:00Z",
    "completed_at": "2026-05-21T10:00:03Z",
    "duration_ms": 3000,
    "iteration": null,
    "is_iteration": false,
    "handle_inputs": {},
    "handle_outputs": {},
    "fingerprint": {
      "input_fingerprint": "inp_abc",
      "schema_fingerprint": "sch_abc",
      "definition_fingerprint": "def_abc",
      "resolved_definition_fingerprint": "rdef_abc",
      "effective_execution_fingerprint": "exec_abc",
      "handle_inputs_fingerprint": "handles_abc",
      "effective_config": {},
      "runtime_overrides": {},
      "cohort_id": null,
      "source_file_id": null,
      "source_filename": null
    }
  }
]

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.

Query joined step rows for a workflow. Use this when you need step lifecycle, handle payloads, and execution fingerprints in one flat result. 
from retab import Retab
from retab.types.workflows import StepsQueryRequest

client = Retab()

steps = client.workflows.steps.query(
    StepsQueryRequest(
        workflow_id="wf_abc123",
        block_type="extract",
        status=["completed"],
        limit=20,
    )
)

for step in steps:
    print(step.step_id, step.status, step.fingerprint)

[
  {
    "step_id": "step_abc123",
    "run_id": "run_abc123",
    "workflow_id": "wf_abc123",
    "block_id": "extract-1",
    "block_type": "extract",
    "status": "completed",
    "started_at": "2026-05-21T10:00:00Z",
    "completed_at": "2026-05-21T10:00:03Z",
    "duration_ms": 3000,
    "iteration": null,
    "is_iteration": false,
    "handle_inputs": {},
    "handle_outputs": {},
    "fingerprint": {
      "input_fingerprint": "inp_abc",
      "schema_fingerprint": "sch_abc",
      "definition_fingerprint": "def_abc",
      "resolved_definition_fingerprint": "rdef_abc",
      "effective_execution_fingerprint": "exec_abc",
      "handle_inputs_fingerprint": "handles_abc",
      "effective_config": {},
      "runtime_overrides": {},
      "cohort_id": null,
      "source_file_id": null,
      "source_filename": null
    }
  }
]

Authorizations

​
Api-Key
string
header
required

Body

application/json

Request body for POST /v1/workflows/steps/query.

Filters mirror the indexed columns on step_fingerprints so the $match stage stays index-friendly. Status is the one filter that targets the joined workflow_run_steps document (applied as a post-$lookup $match on lifecycle.status).

​
workflow_id
string
required
​
block_id
string | null
​
block_type
string | null
​
source_kind
string | null
​
status
string[] | null
​
limit
integer | null
Required range: 1 <= x <= 1000

Response

Successful Response

​
step_id
string
required
​
run_id
string
required
​
workflow_id
string
required
​
block_id
string
required
​
block_type
string
required
​
status
string
required
​
started_at
string<date-time> | null
​
completed_at
string<date-time> | null
​
duration_ms
integer | null
​
iteration
integer | null
​
is_iteration
boolean
default:false
​
handle_inputs
Handle Inputs · object
​
handle_outputs
Handle Outputs · object
​
fingerprint
StepFingerprintJoined · object

Slim fingerprint projection embedded in StepQueryResult.