Skip to main content
GET
/
v1
/
workflows
/
runs
/
{run_id}
/
steps
/
{block_id}
/
simulations
from retab import Retab

client = Retab()

simulations = client.workflows.blocks.list_simulations(
    "run_abc123xyz",
    "extract-1",
    limit=10,
)

for sim in simulations.data:
    print(sim.id, sim.success, sim.duration_ms)
{
  "data": [
    {
      "id": "sim_4jHpQRxX8mnY",
      "workflow_id": "wf_abc123xyz",
      "run_id": "run_abc123xyz",
      "block_id": "extract-1",
      "block_type": "extract",
      "success": true,
      "handle_outputs": {
        "output-json-0": {
          "type": "json",
          "data": {
            "invoice_number": "INV-2024-001",
            "total": 1234.56
          }
        }
      },
      "artifact": { "operation": "extraction", "id": "ext_kP7zRn2H" },
      "duration_ms": 824,
      "skipped": false,
      "created_at": "2026-04-15T11:24:00Z"
    },
    {
      "id": "sim_9BqxJV4PtKwm",
      "workflow_id": "wf_abc123xyz",
      "run_id": "run_abc123xyz",
      "block_id": "extract-1",
      "block_type": "extract",
      "success": false,
      "error": "model returned malformed JSON",
      "duration_ms": 612,
      "skipped": false,
      "created_at": "2026-04-15T11:18:00Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": 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.

List recent simulation results for a block in a workflow run, newest first. Each entry is a stored simulation produced by Simulate Block — includes the captured handle inputs, the produced outputs, the optional artifact ref to a persisted result, and the draft block config that was used. 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 limit (default 20, max 100) to bound the page size.
from retab import Retab

client = Retab()

simulations = client.workflows.blocks.list_simulations(
    "run_abc123xyz",
    "extract-1",
    limit=10,
)

for sim in simulations.data:
    print(sim.id, sim.success, sim.duration_ms)
{
  "data": [
    {
      "id": "sim_4jHpQRxX8mnY",
      "workflow_id": "wf_abc123xyz",
      "run_id": "run_abc123xyz",
      "block_id": "extract-1",
      "block_type": "extract",
      "success": true,
      "handle_outputs": {
        "output-json-0": {
          "type": "json",
          "data": {
            "invoice_number": "INV-2024-001",
            "total": 1234.56
          }
        }
      },
      "artifact": { "operation": "extraction", "id": "ext_kP7zRn2H" },
      "duration_ms": 824,
      "skipped": false,
      "created_at": "2026-04-15T11:24:00Z"
    },
    {
      "id": "sim_9BqxJV4PtKwm",
      "workflow_id": "wf_abc123xyz",
      "run_id": "run_abc123xyz",
      "block_id": "extract-1",
      "block_type": "extract",
      "success": false,
      "error": "model returned malformed JSON",
      "duration_ms": 612,
      "skipped": false,
      "created_at": "2026-04-15T11:18:00Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

Authorizations

Api-Key
string
header
required

Path Parameters

run_id
string
required
block_id
string
required

Query Parameters

limit
integer
default:20
Required range: 1 <= x <= 100

Response

Successful Response

id
string
required

Unique simulation ID

workflow_id
string
required

Workflow the block belongs to

run_id
string
required

Run whose inputs were used

block_id
string
required

ID of the block that was simulated

block_type
string
required

Type of the block

success
boolean
required

Whether simulation succeeded

handle_inputs
Handle Inputs · object

Input payloads keyed by handle ID (file metadata for files, data for json)

artifact
StepArtifactRef · object

Canonical persisted-ref artifact for this simulation (operation + id), if any

handle_outputs
Handle Outputs · object

Output payloads keyed by handle ID

routing_decision
string[] | null

Active output handles for routing decisions

error
string | null

Error message if simulation failed

duration_ms
number | null

Duration of the simulation in milliseconds

skipped
boolean
default:false

Whether the block was skipped due to missing inputs

created_at
string<date-time>
block_config
Block Config · object

The draft block config used for this simulation

step_id
string | null

The step ID that was used for inputs (includes iteration prefix if applicable)

available_iterations
Available Iterations · object[] | null

When the block has multiple iterations, lists all available ones