Get Experiment Run

Retrieve a single experiment run.

Identified by run_id. Returns the run with its lifecycle status, timing, score, and document progress counts. Returns 404 if no run with that ID exists.

GET /v1/workflows/experiments/runs/{run_id}

Python

from retab import Retab

client = Retab()

run = client.workflows.experiments.runs.get("exprun_2")
print(run.lifecycle.status, run.completed_document_count)

200

{
  "id": "exprun_2",
  "workflow": {
    "workflow_id": "wf_abc123",
    "version_id": "draft_2026_05_18"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "status": "completed" },
  "timing": {
    "created_at": "2026-05-02T11:00:00Z",
    "started_at": "2026-05-02T11:00:01Z",
    "completed_at": "2026-05-02T11:04:18Z",
    "duration_ms": 258221
  },
  "experiment_id": "exp_abc",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 5,
  "total_document_count": 12,
  "completed_document_count": 12,
  "error_count": 0,
  "score": 0.87,
  "definition_fingerprint": "0ff93ddc7cefcb42",
  "documents_fingerprint": "ddd95baadce6045f"
}

Fetch an experiment run by run_id. Use this while polling for lifecycle.status, then inspect child records with List Experiment Run Results or metrics with Get Experiment Run Metrics.

Python

from retab import Retab

client = Retab()

run = client.workflows.experiments.runs.get("exprun_2")
print(run.lifecycle.status, run.completed_document_count)

200

{
  "id": "exprun_2",
  "workflow": {
    "workflow_id": "wf_abc123",
    "version_id": "draft_2026_05_18"
  },
  "trigger": { "type": "api" },
  "lifecycle": { "status": "completed" },
  "timing": {
    "created_at": "2026-05-02T11:00:00Z",
    "started_at": "2026-05-02T11:00:01Z",
    "completed_at": "2026-05-02T11:04:18Z",
    "duration_ms": 258221
  },
  "experiment_id": "exp_abc",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 5,
  "total_document_count": 12,
  "completed_document_count": 12,
  "error_count": 0,
  "score": 0.87,
  "definition_fingerprint": "0ff93ddc7cefcb42",
  "documents_fingerprint": "ddd95baadce6045f"
}

Authorizations

Api-Key · string · header · required

Path Parameters

run_id · string · required

Response

200

application/json

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

Show child attributes

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.

PendingWorkflowExperimentRun

QueuedWorkflowExperimentRun

RunningWorkflowExperimentRun

CompletedWorkflowExperimentRun

ErrorWorkflowExperimentRun

CancelledWorkflowExperimentRun

Show child attributes

timing · ExperimentRunTiming · object · required

Show child attributes

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