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

client = Retab()

experiment = client.workflows.experiments.create(
    workflow_id="wf_abc123",
    block_id="extract-invoice",
    name="Q1 invoices",
    document_captures=[
        {"workflow_run_id": "wfrun_1"},
        {"workflow_run_id": "wfrun_2", "step_id": "for_each-0"},
    ],
    n_consensus=5,
)
print(experiment.id)

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 5,
  "document_count": 2,
  "name": "Q1 invoices",
  "last_run_id": null,
  "status": "draft",
  "score": null,
  "job_id": null,
  "is_stale": false,
  "schema_drift": "unknown",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

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 consensus experiment on a supported block (extract, classifier, split, or for_each configured with map_method="split_by_key"). The experiment freezes a name, a fixed document set, and a consensus count — but does NOT run metrics. Trigger the first run with Run Experiment. Provide documents through one or both of:
  • document_captures — references to past workflow runs. The handle inputs the block actually received are materialized server-side.
  • documents — explicit handle inputs you assemble yourself, optionally carrying provenance metadata.
n_consensus must be 3, 5, or 7. See Experiments for the full conceptual model. 
from retab import Retab

client = Retab()

experiment = client.workflows.experiments.create(
    workflow_id="wf_abc123",
    block_id="extract-invoice",
    name="Q1 invoices",
    document_captures=[
        {"workflow_run_id": "wfrun_1"},
        {"workflow_run_id": "wfrun_2", "step_id": "for_each-0"},
    ],
    n_consensus=5,
)
print(experiment.id)

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 5,
  "document_count": 2,
  "name": "Q1 invoices",
  "last_run_id": null,
  "status": "draft",
  "score": null,
  "job_id": null,
  "is_stale": false,
  "schema_drift": "unknown",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
workflow_id
string
required

Query Parameters

​
access_token
string | null

Body

application/json
​
block_id
string
required
​
name
string
required
​
document_captures
ExperimentDocumentCaptureRequest · object[] | null
​
documents
ExplicitExperimentDocumentRequest · object[] | null
​
n_consensus
enum<integer>
default:5
Available options:
3,
5,
7

Response

Successful Response

​
id
string
required
​
workflow_id
string
required
​
block_id
string
required
​
n_consensus
enum<integer>
required
Available options:
3,
5,
7
​
name
string
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
block_kind
enum<string>
required
Available options:
extract,
classifier,
split,
for_each
​
document_count
integer
default:0
​
last_run_id
string | null
​
status
enum<string>
default:draft
Available options:
draft,
processing,
completed,
failed,
cancelled
​
score
number | null
​
job_id
string | null
​
is_stale
boolean
default:false
​
schema_drift
enum<string>
default:unknown
Available options:
none,
partial,
drifted,
unknown
​
schema_drift_detail
string | null