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
}
}
Runs
Create Workflow Test Run
Create a workflow-scoped test run.
workflow_id is the execution context. Optional scope narrows the
run to one saved test or one block; omitted scope runs all workflow tests.
POST
/
v1
/
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 bytest_id.scope.type = "block"- run every saved test for one block byblock_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
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.
Response
Successful Response
A batch execution of a workflow's tests, with overall lifecycle, timing, and pass/fail counts.
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
Show child attributes
The test run has been created but execution has not started.
- PendingWorkflowTestRun
- QueuedWorkflowTestRun
- RunningWorkflowTestRun
- CompletedWorkflowTestRun
- ErrorWorkflowTestRun
- CancelledWorkflowTestRun
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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
Show child attributes
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
Show child attributes
Show child attributes
Show child attributes