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,
)
import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const block_execution = await client.workflows.blocks.executions.create("run_abc123xyz", "blk_extract_1", "step_iter_0_blk_extract_1", 5);
block_execution, err := client.Workflows.Blocks.Executions.Create(ctx, &retab.WorkflowBlockExecutionsCreateParams{
	RunID:      ptr("run_abc123xyz"),
	BlockID:    ptr("blk_extract_1"),
	StepID:     ptr("step_iter_0_blk_extract_1"),
	NConsensus: ptr(5),
})
require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

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,
)
use retab::models::CreateBlockExecutionRequest;
use retab::resources::workflow_block_executions::CreateParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let block_execution = client
        .workflows().blocks().executions()
        .create(CreateParams::new(CreateBlockExecutionRequest {
            run_id: "run_abc123xyz".into(),
            block_id: "blk_extract_1".into(),
            step_id: Some("step_iter_0_blk_extract_1".into()),
            n_consensus: Some(5),
            check_eligibility: None,
        }))
        .await?;

    println!("{}", block_execution.id);
    Ok(())
}
<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->workflows()->blocks()->executions()->create(
    runId: 'run_abc123',
    blockId: 'blk_extract_1',
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Workflows.Blocks.Executions.CreateAsync(new WorkflowBlockExecutionsCreateOptions());
Console.WriteLine(result);
import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().blocks().executions().create("run_abc123", "block_abc123", "step_abc123", 10L, null);
    System.out.println(result);
  }
}
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/blocks/executions' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"run_id":"run_abc123xyz","block_id":"blk_extract_1"}'
{
  "id": "wfsim_abc123",
  "run_id": "run_abc123xyz",
  "block_id": "blk_extract_1",
  "lifecycle": { "status": "completed" }
}
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,
)
import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const block_execution = await client.workflows.blocks.executions.create("run_abc123xyz", "blk_extract_1", "step_iter_0_blk_extract_1", 5);
block_execution, err := client.Workflows.Blocks.Executions.Create(ctx, &retab.WorkflowBlockExecutionsCreateParams{
	RunID:      ptr("run_abc123xyz"),
	BlockID:    ptr("blk_extract_1"),
	StepID:     ptr("step_iter_0_blk_extract_1"),
	NConsensus: ptr(5),
})
require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

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,
)
use retab::models::CreateBlockExecutionRequest;
use retab::resources::workflow_block_executions::CreateParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let block_execution = client
        .workflows().blocks().executions()
        .create(CreateParams::new(CreateBlockExecutionRequest {
            run_id: "run_abc123xyz".into(),
            block_id: "blk_extract_1".into(),
            step_id: Some("step_iter_0_blk_extract_1".into()),
            n_consensus: Some(5),
            check_eligibility: None,
        }))
        .await?;

    println!("{}", block_execution.id);
    Ok(())
}
<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->workflows()->blocks()->executions()->create(
    runId: 'run_abc123',
    blockId: 'blk_extract_1',
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Workflows.Blocks.Executions.CreateAsync(new WorkflowBlockExecutionsCreateOptions());
Console.WriteLine(result);
import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().blocks().executions().create("run_abc123", "block_abc123", "step_abc123", 10L, null);
    System.out.println(result);
  }
}
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/blocks/executions' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"run_id":"run_abc123xyz","block_id":"blk_extract_1"}'
{
  "id": "wfsim_abc123",
  "run_id": "run_abc123xyz",
  "block_id": "blk_extract_1",
  "lifecycle": { "status": "completed" }
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Re-run a single block.

block_id is the block to run; run_id is the workflow run that supplied the original inputs. step_id optionally selects a specific step whose inputs should be used, which is useful for blocks inside a for_each loop.

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 to look up the step.

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

The result of executing a single workflow block.

The execution state is carried by the lifecycle field.

id
string
required

Unique block execution ID

workflow_id
string
required

Workflow the block belongs to

source_run_id
string
required

Workflow 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
PendingBlockExecutionLifecycle · object
required

The execution row exists but has not been dispatched.

workflow_version_id
string

Workflow version whose source run supplied inputs

handle_inputs
Handle Inputs · object · null · null

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

artifact
StepArtifactRef · object | null

Reference to the artifact produced by this block execution, if any.

handle_outputs
Handle Outputs · object · null · null

Output payloads keyed by handle ID

routing_decisions
string[] | null

Active output handles for routing decisions

duration_ms
number | null

Duration of the block execution in milliseconds

created_at
string<date-time>

When the block execution record was created

started_at
string<date-time>

When the block execution started

completed_at
string<date-time>

When the block execution completed

handle_inputs_fingerprint
string
workflow_draft_fingerprint
string
block_execution_fingerprint
string
execution_fingerprint
string
block_config
Block Config · object | null

The draft block config used for this block execution

source_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