Update Experiment

Update an experiment.

Identified by experiment_id. Send any of name, n_consensus, documents, or document_captures; omitted fields are left unchanged. Returns the updated experiment with its latest-run status and drift info.

PATCH /v1/workflows/experiments/{experiment_id}

Python

from retab import Retab

client = Retab()

# Bump consensus from 5 to 7
client.workflows.experiments.update(
    experiment_id="exp_abc",
    n_consensus=7,
)

# Or rename only
client.workflows.experiments.update(
    experiment_id="exp_abc",
    name="Q1 invoices — v2",
)

200

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 7,
  "document_count": 12,
  "name": "Q1 invoices",
  "last_run_id": "exprun_1",
  "status": "completed",
  "score": 0.87,
  "is_stale": true,
  "schema_drift": "none",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-02T11:00:00Z"
}

Patch the name, document set, or n_consensus of an experiment. Only fields included in the body are updated — omit a field to leave it untouched.

Changing the document set (document_captures / documents) or n_consensus invalidates existing metrics. Call Run Experiment afterwards to recompute.

Python

from retab import Retab

client = Retab()

# Bump consensus from 5 to 7
client.workflows.experiments.update(
    experiment_id="exp_abc",
    n_consensus=7,
)

# Or rename only
client.workflows.experiments.update(
    experiment_id="exp_abc",
    name="Q1 invoices — v2",
)

200

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 7,
  "document_count": 12,
  "name": "Q1 invoices",
  "last_run_id": "exprun_1",
  "status": "completed",
  "score": 0.87,
  "is_stale": true,
  "schema_drift": "none",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-02T11:00:00Z"
}

Authorizations

Api-Key · string · header · required

Path Parameters

experiment_id · string · required

Body

application/json

Body for updating an experiment. Only the supplied fields are changed.

document_captures · ExperimentDocumentCaptureRequest · object[] | null

Show child attributes

documents · ExplicitExperimentDocumentRequest · object[] | null

Show child attributes

n_consensus · enum<integer> | null

Available options: 3, 5, 7

name · string | null

Response

200

application/json

Successful Response

An experiment that evaluates a workflow block against a set of documents, with its latest run status and score.

id · string · required

workflow_id · string · required

block_id · string · required

n_consensus · enum<integer> · required

Available options: 3, 5, 7

name · string · required

block_type · enum<string> · required

Available options: extract, classifier, split, for_each

document_count · integer · default: 0

last_run_id · string | null

created_at · string<date-time>

When the experiment was created

updated_at · string<date-time>

When the experiment was last updated

status · enum<string> · default: draft

Available options: draft, processing, completed, failed, cancelled

score · number | null

is_stale · boolean · default: false

freshness · ArtifactFreshness · object

Show child attributes

schema_drift · enum<string> · default: unknown

Available options: none, partial, drifted, unknown

schema_drift_detail · string | null

drift · ArtifactDrift · object

Show child attributes