Create Workflow Test Run

from retab import Retab

client = Retab()

run = client.workflows.tests.runs.create(
    workflow_id="wf_abc123xyz",
    scope={
        "type": "single",
        "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
    },
)

print(run.id, run.lifecycle.status)

import { Retab } from "@retab/node";

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

const run = await client.workflows.tests.runs.create("wf_abc123xyz", {
  type: "single",
  testId: "wfnodetest_hsLEQiM61ez9Piv147MWk",
});

console.log(run.id, run.lifecycle.status);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	run, err := client.Workflows.Tests.Runs.Create(ctx, &retab.WorkflowTestRunsCreateParams{
		WorkflowID: "wf_abc123xyz",
		Scope: &retab.WorkflowTestRunScope{
			Type:   retab.WorkflowTestRunScopeTypeSingle,
			TestID: ptr("wfnodetest_hsLEQiM61ez9Piv147MWk"),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(run.ID, run.Lifecycle.Status())
}

require 'retab'

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

run = client.workflow_test_runs.create(
  workflow_id: 'wf_abc123xyz',
  scope: {
    type: 'single',
    test_id: 'wfnodetest_hsLEQiM61ez9Piv147MWk',
  },
)

puts "#{run.id} #{run.lifecycle.status}"

use retab::models::{CreateWorkflowTestRunRequest, WorkflowTestRunSingleScope};
use retab::resources::workflow_test_runs::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 run = client
        .workflows().tests().runs()
        .create(CreateParams::new(CreateWorkflowTestRunRequest {
            workflow_id: "wf_abc123xyz".into(),
            scope: Some(WorkflowTestRunSingleScope {
                type_: "single".into(),
                test_id: "wfnodetest_hsLEQiM61ez9Piv147MWk".into(),
            }.into()),
        }))
        .await?;
    println!("{} {:?}", run.id, run.lifecycle);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

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

$result = $client->workflowTestRuns()->create();
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.Tests.Runs.CreateAsync(
    new WorkflowTestRunsCreateOptions
    {
        WorkflowId = "wf_abc123xyz",
        Scope = new WorkflowTestRunSingleScope
        {
            TestId = "wfnodetest_hsLEQiM61ez9Piv147MWk",
        },
    }
);
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().tests().runs().create("wf_abc123", null);
    System.out.println(result);
  }
}

# Single test
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/tests/runs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "workflow_id": "wf_abc123xyz",
    "scope": {
      "type": "single",
      "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk"
    }
  }'

# All tests for one block
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/tests/runs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "workflow_id": "wf_abc123xyz",
    "scope": { "type": "block", "block_id": "block_extract_invoice" }
  }'

{
  "id": "wftestrun_q1z2",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "version_id": "draft_2026_05_18"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "status": "pending" },
  "timing": {
    "created_at": "2026-05-18T10:00:00Z",
    "started_at": null,
    "completed_at": null
  },
  "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
  "target": { "type": "block", "block_id": "block_extract_invoice" },
  "total_tests": 1,
  "counts": {
    "queued": 1,
    "running": 0,
    "passed": 0,
    "failed": 0,
    "blocked": 0,
    "error": 0,
    "cancelled": 0
  }
}

POST

workflows

tests

runs

from retab import Retab

client = Retab()

run = client.workflows.tests.runs.create(
    workflow_id="wf_abc123xyz",
    scope={
        "type": "single",
        "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
    },
)

print(run.id, run.lifecycle.status)

import { Retab } from "@retab/node";

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

const run = await client.workflows.tests.runs.create("wf_abc123xyz", {
  type: "single",
  testId: "wfnodetest_hsLEQiM61ez9Piv147MWk",
});

console.log(run.id, run.lifecycle.status);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	run, err := client.Workflows.Tests.Runs.Create(ctx, &retab.WorkflowTestRunsCreateParams{
		WorkflowID: "wf_abc123xyz",
		Scope: &retab.WorkflowTestRunScope{
			Type:   retab.WorkflowTestRunScopeTypeSingle,
			TestID: ptr("wfnodetest_hsLEQiM61ez9Piv147MWk"),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(run.ID, run.Lifecycle.Status())
}

require 'retab'

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

run = client.workflow_test_runs.create(
  workflow_id: 'wf_abc123xyz',
  scope: {
    type: 'single',
    test_id: 'wfnodetest_hsLEQiM61ez9Piv147MWk',
  },
)

puts "#{run.id} #{run.lifecycle.status}"

use retab::models::{CreateWorkflowTestRunRequest, WorkflowTestRunSingleScope};
use retab::resources::workflow_test_runs::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 run = client
        .workflows().tests().runs()
        .create(CreateParams::new(CreateWorkflowTestRunRequest {
            workflow_id: "wf_abc123xyz".into(),
            scope: Some(WorkflowTestRunSingleScope {
                type_: "single".into(),
                test_id: "wfnodetest_hsLEQiM61ez9Piv147MWk".into(),
            }.into()),
        }))
        .await?;
    println!("{} {:?}", run.id, run.lifecycle);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

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

$result = $client->workflowTestRuns()->create();
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.Tests.Runs.CreateAsync(
    new WorkflowTestRunsCreateOptions
    {
        WorkflowId = "wf_abc123xyz",
        Scope = new WorkflowTestRunSingleScope
        {
            TestId = "wfnodetest_hsLEQiM61ez9Piv147MWk",
        },
    }
);
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().tests().runs().create("wf_abc123", null);
    System.out.println(result);
  }
}

# Single test
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/tests/runs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "workflow_id": "wf_abc123xyz",
    "scope": {
      "type": "single",
      "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk"
    }
  }'

# All tests for one block
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/tests/runs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "workflow_id": "wf_abc123xyz",
    "scope": { "type": "block", "block_id": "block_extract_invoice" }
  }'

{
  "id": "wftestrun_q1z2",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "version_id": "draft_2026_05_18"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "status": "pending" },
  "timing": {
    "created_at": "2026-05-18T10:00:00Z",
    "started_at": null,
    "completed_at": null
  },
  "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
  "target": { "type": "block", "block_id": "block_extract_invoice" },
  "total_tests": 1,
  "counts": {
    "queued": 1,
    "running": 0,
    "passed": 0,
    "failed": 0,
    "blocked": 0,
    "error": 0,
    "cancelled": 0
  }
}

Create a workflow-test run against the current workflow draft. A run can execute one saved test, every test for one block, or every test in the workflow. The canonical route is flat: send workflow_id in the request body and optionally narrow execution with scope. If scope is omitted, every saved test in the workflow runs. The response is a run resource. Use its id with the run-id-first endpoints: Get Workflow Test Run, List Test Run Results. The request body has a workflow context and an optional scope:

omitted scope - run every saved test in the workflow.
scope.type = "single" - run one saved test by test_id.
scope.type = "block" - run every saved test for one block by block_id.

from retab import Retab

client = Retab()

run = client.workflows.tests.runs.create(
    workflow_id="wf_abc123xyz",
    scope={
        "type": "single",
        "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
    },
)

print(run.id, run.lifecycle.status)

import { Retab } from "@retab/node";

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

const run = await client.workflows.tests.runs.create("wf_abc123xyz", {
  type: "single",
  testId: "wfnodetest_hsLEQiM61ez9Piv147MWk",
});

console.log(run.id, run.lifecycle.status);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	run, err := client.Workflows.Tests.Runs.Create(ctx, &retab.WorkflowTestRunsCreateParams{
		WorkflowID: "wf_abc123xyz",
		Scope: &retab.WorkflowTestRunScope{
			Type:   retab.WorkflowTestRunScopeTypeSingle,
			TestID: ptr("wfnodetest_hsLEQiM61ez9Piv147MWk"),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(run.ID, run.Lifecycle.Status())
}

require 'retab'

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

run = client.workflow_test_runs.create(
  workflow_id: 'wf_abc123xyz',
  scope: {
    type: 'single',
    test_id: 'wfnodetest_hsLEQiM61ez9Piv147MWk',
  },
)

puts "#{run.id} #{run.lifecycle.status}"

use retab::models::{CreateWorkflowTestRunRequest, WorkflowTestRunSingleScope};
use retab::resources::workflow_test_runs::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 run = client
        .workflows().tests().runs()
        .create(CreateParams::new(CreateWorkflowTestRunRequest {
            workflow_id: "wf_abc123xyz".into(),
            scope: Some(WorkflowTestRunSingleScope {
                type_: "single".into(),
                test_id: "wfnodetest_hsLEQiM61ez9Piv147MWk".into(),
            }.into()),
        }))
        .await?;
    println!("{} {:?}", run.id, run.lifecycle);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

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

$result = $client->workflowTestRuns()->create();
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.Tests.Runs.CreateAsync(
    new WorkflowTestRunsCreateOptions
    {
        WorkflowId = "wf_abc123xyz",
        Scope = new WorkflowTestRunSingleScope
        {
            TestId = "wfnodetest_hsLEQiM61ez9Piv147MWk",
        },
    }
);
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().tests().runs().create("wf_abc123", null);
    System.out.println(result);
  }
}

# Single test
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/tests/runs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "workflow_id": "wf_abc123xyz",
    "scope": {
      "type": "single",
      "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk"
    }
  }'

# All tests for one block
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/tests/runs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "workflow_id": "wf_abc123xyz",
    "scope": { "type": "block", "block_id": "block_extract_invoice" }
  }'

{
  "id": "wftestrun_q1z2",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "version_id": "draft_2026_05_18"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "status": "pending" },
  "timing": {
    "created_at": "2026-05-18T10:00:00Z",
    "started_at": null,
    "completed_at": null
  },
  "test_id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
  "target": { "type": "block", "block_id": "block_extract_invoice" },
  "total_tests": 1,
  "counts": {
    "queued": 1,
    "running": 0,
    "passed": 0,
    "failed": 0,
    "blocked": 0,
    "error": 0,
    "cancelled": 0
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Create a workflow test run. Provide a workflow_id, and optionally narrow execution with scope to a single test or one block. Omit scope to run every saved workflow test.

workflow_id

string

required

scope

WorkflowTestRunSingleScope · object

Run one saved workflow test in the workflow.

WorkflowTestRunSingleScope
WorkflowTestRunWorkflowScope
WorkflowTestRunBlockScope

Show child attributes

Response

Successful Response

A batch execution of a workflow's tests, with overall lifecycle, timing, and pass/fail counts.

string

required

workflow_id

string

required

workflow_version_id

string

required

trigger

TriggerInfo · object

required

Public summary of what started a run: just the trigger category.

The full per-variant detail (schedule_id, parent_run_id, sender, ...) is kept internally on StoredWorkflowRun.trigger but intentionally not exposed in the public API surface.

Show child attributes

lifecycle

PendingWorkflowTestRun · object

required

The test run has been created but execution has not started.

Show child attributes

timing

WorkflowTestRunTiming · object

required

Show child attributes

total_tests

integer

required

target

WorkflowTestBlockTarget · object | null

Public workflow-test target.

The storage layer remains block-scoped today, but the API shape names the tested entity explicitly so workflow-level targets can be added later.

Show child attributes

test_id

string | null

counts

BlockTestBatchExecutionCounts · object

Aggregate counts for a batch of block-test runs.

Each individual run contributes to exactly one lifecycle_counts bucket, and additionally to one outcome bucket when lifecycle_counts.completed is incremented.

Show child attributes

freshness

ArtifactFreshness · object

Show child attributes