Skip to main content
POST
/
v1
/
workflows
/
experiments
/
runs
from retab import Retab

client = Retab()

run = client.workflows.experiments.runs.create(
    workflow_id="wf_abc123",
    experiment_id="exp_abc",
)
print(run.id, run.lifecycle.status)

# Wait for the run to complete, then read metrics.
metrics = client.workflows.experiments.metrics.get(
    run.id,
    view="summary",
)

{
  "id": "exprun_2",
  "workflow": {
    "workflow_id": "wf_abc123",
    "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
  },
  "experiment_id": "exp_abc",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "definition_fingerprint": "0ff93ddc7cefcb42",
  "documents_fingerprint": "ddd95baadce6045f",
  "total_document_count": 12,
  "completed_document_count": 0,
  "error_count": 0,
  "n_consensus": 5
}
Trigger an experiment run with the current draft block configuration. The canonical API route is flat: send experiment_id in the request body. workflow_id is optional in the body and scopes the lookup when provided. This is the call that produces metrics: it re-processes every experiment document through the block with n_consensus parallel passes per document. Use it after creating an experiment, after editing the block, or after changing the document set. The endpoint is async - it returns a run resource immediately. Poll the experiment run with Get Experiment Run until it reaches a terminal status, then read metrics with Get Experiment Run Metrics. Runs use the experiment’s stored n_consensus and document set. 
from retab import Retab

client = Retab()

run = client.workflows.experiments.runs.create(
    workflow_id="wf_abc123",
    experiment_id="exp_abc",
)
print(run.id, run.lifecycle.status)

# Wait for the run to complete, then read metrics.
metrics = client.workflows.experiments.metrics.get(
    run.id,
    view="summary",
)

{
  "id": "exprun_2",
  "workflow": {
    "workflow_id": "wf_abc123",
    "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
  },
  "experiment_id": "exp_abc",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "definition_fingerprint": "0ff93ddc7cefcb42",
  "documents_fingerprint": "ddd95baadce6045f",
  "total_document_count": 12,
  "completed_document_count": 0,
  "error_count": 0,
  "n_consensus": 5
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Request body to create an experiment run.

workflow_id is optional; when omitted it is taken from the experiment, and when supplied it must match the experiment's workflow.

​
experiment_id
string
required

The experiment to create a run for.

​
workflow_id
string | null

Optional. When omitted, the workflow is derived from the experiment record. When supplied, must match the experiment's workflow_id (404 otherwise).

Response

Successful Response

A single execution of an experiment, identified by id.

​
id
string
required
​
workflow_id
string
required
​
workflow_version_id
string
required
​
trigger
ExperimentRunTrigger · object
required
​
experiment_id
string
required
​
block_id
string
required
​
block_type
enum<string>
required
Available options:
extract,
classifier,
split,
for_each
​
n_consensus
enum<integer>
required
Available options:
3,
5,
7
​
lifecycle
PendingWorkflowExperimentRun · object
required

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

​
timing
ExperimentRunTiming · object
required
​
definition_fingerprint
string
required
​
documents_fingerprint
string
required
​
parent_run_id
string | null
​
block_version_id
string | null
​
metrics_validity_fingerprint
string | null
​
metrics_validity_fingerprint_version
integer | null
​
score
number | null
​
total_document_count
integer
default:0
​
completed_document_count
integer
default:0
​
document_count
integer
default:0
​
error_count
integer
default:0