Skip to main content
GET
/
v1
/
workflows
/
experiments
/
runs
/
{run_id}
from retab import Retab

client = Retab()

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

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

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.

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. 
from retab import Retab

client = Retab()

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

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

Successful Response

Run-id-first public experiment run shape.

The canonical identity is id. Internal queue handles and duplicate identity aliases are intentionally absent.

​
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
ExperimentRunTrigger · object
required
​
experiment_id
string
required
​
block_id
string
required
​
block_kind
enum<string>
required
Available options:
extract,
classifier,
split,
for_each
​
n_consensus
enum<integer>
required
Available options:
3,
5,
7
​
lifecycle
ExperimentRunLifecycle · object
required
​
timing
ExperimentRunTiming · object
required
​
definition_fingerprint
string
required
​
documents_fingerprint
string
required
​
parent_run_id
string | 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