Skip to main content
POST
/
v1
/
workflows
/
blocks
/
executions
from retab import Retab

client = Retab()

block_execution = client.workflows.blocks.executions.create(
    run_id="run_abc123xyz",
    block_id="blk_extract_1",
    step_id="step_iter_0_blk_extract_1",
    n_consensus=5,
)

{
  "id": "wfsim_abc123",
  "run_id": "run_abc123xyz",
  "block_id": "blk_extract_1",
  "lifecycle": { "status": "completed" }
}

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.

Create a workflow block execution from a prior run. 
from retab import Retab

client = Retab()

block_execution = client.workflows.blocks.executions.create(
    run_id="run_abc123xyz",
    block_id="blk_extract_1",
    step_id="step_iter_0_blk_extract_1",
    n_consensus=5,
)

{
  "id": "wfsim_abc123",
  "run_id": "run_abc123xyz",
  "block_id": "blk_extract_1",
  "lifecycle": { "status": "completed" }
}

Authorizations

​
Api-Key
string
header
required

Body

application/json

Body for POST /v1/workflows/blocks/executions.

block_id is the block to replay; run_id is the workflow run that sourced the original step's handle_inputs. step_id optionally pins a concrete step row whose inputs should be used, which is useful for iteration-prefixed for_each body steps.

​
run_id
string
required

Workflow run id that owns the step.

​
block_id
string
required

Workflow block id to execute.

​
step_id
string | null

Optional concrete step id whose inputs should be used. When omitted, the block id is used as the canonical step lookup key.

​
n_consensus
integer | null

Optional override for n_consensus on extract / split / classifier blocks. Must be 3, 5, or 7.

​
check_eligibility
boolean
default:true

Whether to verify the upstream subgraph hasn't drifted since the source run. Disable only for explicit force-rerun flows.

Response

Successful Response

Public block execution result for a single workflow block.

Terminal state is carried by the discriminated lifecycle union. The legacy flat success / error / skipped fields were removed in the hard cutover — they let invalid combinations (success=true with a non-empty error) be representable on the wire and forced consumers to know an undocumented field-precedence rule.

​
id
string
required

Unique block execution 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 executed

​
block_type
string
required

Type of the block

​
lifecycle
CompletedBlockExecutionLifecycle · object
required

Terminal: the executed block executed successfully.

​
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 block execution (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

​
duration_ms
number | null

Duration of the block execution in milliseconds

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

The draft block config used for this block execution

​
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