Simulate Block

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.

1. Looks up the run and verifies the upstream subgraph hasn’t drifted since it executed (skip with check_eligibility=false).
2. Fetches the block’s handle_inputs from the run’s recorded step data.
3. Loads the block’s current draft config (not the published snapshot).
4. Executes the block.
5. Returns the produced outputs and a canonical artifact ref where the block produces a persisted resource (extract → extraction, split → split, etc.).

• n_consensus — 3 / 5 / 7. Only meaningful for extract, split, and classifier blocks; ignored otherwise.
• step_id — for blocks inside a for_each or while_loop, pick a specific iteration. Defaults to the base step or the first iteration.
• check_eligibility — defaults to true. Returns 409 if the upstream subgraph changed since run_id executed. Pass false to skip the check.

from retab import Retab

client = Retab()

simulation = client.workflows.blocks.simulate(
    run_id="wfrun_def456",
    block_id="extract-invoice",
    n_consensus=5,
)

if simulation.success:
    print(simulation.handle_outputs)
else:
    print(simulation.error)

{
  "id": "sim_abc",
  "organization_id": "org_123",
  "workflow_id": "wf_abc123",
  "run_id": "wfrun_def456",
  "block_id": "extract-invoice",
  "block_type": "extract",
  "success": true,
  "handle_inputs": {
    "input-document-0": { "type": "file", "filename": "invoice_q1.pdf" }
  },
  "artifact": { "operation": "extraction", "id": "ext_xyz" },
  "handle_outputs": {
    "output-json-0": { "type": "json", "data": { "total": 1234.56 } }
  },
  "duration_ms": 412.0,
  "skipped": false,
  "step_id": "extract-invoice",
  "block_config": { "model": "gpt-5", "json_schema": { "type": "object" } }
}