Skip to main content
POST
/
v1
/
workflows
/
{workflow_id}
/
tests
/
runs
from retab import Retab

client = Retab()

run = client.workflows.tests.runs.create(
    workflow_id="wf_abc123xyz",
    test_id="wfnodetest_hsLEQiM61ez9Piv147MWk",
)

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

{
  "id": "wftestrun_q1z2",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "version_id": "draft_2026_05_18",
    "name_at_run_time": "Invoice workflow",
    "requested_version": "draft"
  },
  "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
  }
}

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-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 response is a run resource. Use its id with the run-id-first endpoints: Get Workflow Test Run, List Test Run Results, and Get Test Run Result. The request body provides exactly one of:
  • test_id - run a single test by id.
  • target - run every test for one block ({ "type": "block", "block_id": "..." }).
  • neither - run every test in the workflow.
n_consensus is optional and only meaningful for extract, split, and classifier blocks. Allowed values are 3, 5, or 7; the override applies to this run only. 
from retab import Retab

client = Retab()

run = client.workflows.tests.runs.create(
    workflow_id="wf_abc123xyz",
    test_id="wfnodetest_hsLEQiM61ez9Piv147MWk",
)

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

{
  "id": "wftestrun_q1z2",
  "workflow": {
    "workflow_id": "wf_abc123xyz",
    "version_id": "draft_2026_05_18",
    "name_at_run_time": "Invoice workflow",
    "requested_version": "draft"
  },
  "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

​
Api-Key
string
header
required

Path Parameters

​
workflow_id
string
required

Body

application/json
​
test_id
string | null
​
target
WorkflowTestBlockTarget · object

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.

​
n_consensus
integer | null

Response

Successful Response

​
id
string
required
​
workflow
WorkflowSnapshotRef · object
required

Reference to the workflow + immutable version that drove the run.

The class name is retained temporarily for compatibility with surrounding run-model code, but public API output uses version_id rather than snapshot identity.

​
trigger
ManualTrigger · object
required

Manual run started by a user from the dashboard.

​
lifecycle
WorkflowTestRunLifecycle · object
required
​
timing
WorkflowTestRunTiming · object
required
​
total_tests
integer
required
​
target
WorkflowTestBlockTarget · object

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.

​
test_id
string | null
​
counts
BlockTestBatchExecutionCounts · object