> ## 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.
# List Experiment Runs
> List experiment runs.
Optionally filter by `workflow_id`, `experiment_id`, `block_id`,
`status`/`exclude_status`, `trigger_type`, and a `from_date`/`to_date`
window. Returns a cursor-paginated list ordered by `sort_by` (default
newest first).
List experiment runs, newest first. Filter by `workflow_id`, `experiment_id`,
`block_id`, lifecycle status, trigger type, date range, or id pagination. For
per-document execution data, use [List Experiment Run Results](/api-reference/workflows/experiments/results/list);
for consensus scores, use [Get Experiment Run Metrics](/api-reference/workflows/experiments/metrics/get).
The response uses the canonical Retab list envelope:
`{ "data": [...], "list_metadata": { "before": null, "after": null } }`.
```python Python theme={null}
from retab import Retab
client = Retab()
page = client.workflows.experiments.runs.list(
experiment_id="exp_abc",
)
for run in page.data:
print(run.id, run.lifecycle.status, run.score)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const page = await client.workflows.experiments.runs.list({
experimentId: "exp_abc",
});
for (const run of page.data) {
console.log(run.id, run.lifecycle.status, run.score);
}
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
retab "github.com/retab-dev/retab/clients/go"
)
func ptr[T any](v T) *T { return &v }
func main() {
ctx := context.Background()
client, err := retab.NewClient("")
if err != nil {
log.Fatal(err)
}
page, err := client.Workflows.Experiments.Runs.List(ctx, &retab.ExperimentRunsListParams{
ExperimentID: ptr("exp_abc"),
})
if err != nil {
log.Fatal(err)
}
for _, run := range page.Data {
fmt.Println(run.ID, run.Lifecycle.Status(), run.Score)
}
}
```
```rust Rust theme={null}
use retab::resources::experiment_runs::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let page = client
.workflows().experiments().runs()
.list(ListParams {
experiment_id: Some("exp_abc".into()),
..Default::default()
})
.await?;
for run in &page.data {
println!("{} {:?} {:?}", run.id, run.lifecycle, run.score);
}
Ok(())
}
```
```php PHP theme={null}
workflows()->experiments()->runs()->list();
print_r($result);
```
```csharp C# theme={null}
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Workflows.Experiments.Runs.ListAsync(new ExperimentRunsListOptions());
Console.WriteLine(result);
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
result = client.workflows.experiments.runs.list
puts result
```
```java Java theme={null}
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.workflows().experiments().runs().list("wf_abc123", "exp_abc123", "block_abc123", null, null, null, null, null, "created_at", null, null, 10L, null);
System.out.println(result);
}
}
```
```curl cURL theme={null}
curl -X 'GET' \
'https://api.retab.com/v1/workflows/experiments/runs?experiment_id=exp_abc' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"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,
"block_execution_fingerprint": "0ff93ddc7cefcb42",
"documents_fingerprint": "ddd95baadce6045f"
}
],
"list_metadata": {
"before": null,
"after": null
}
}
```
## OpenAPI
````yaml GET /v1/workflows/experiments/runs
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows/experiments/runs:
get:
tags:
- Workflows
- Workflow Experiments
summary: List Experiment Runs
description: |-
List experiment runs.
Optionally filter by `workflow_id`, `experiment_id`, `block_id`,
`status`/`exclude_status`, `trigger_type`, and a `from_date`/`to_date`
window. Returns a cursor-paginated list ordered by `sort_by` (default
newest first).
operationId: list_experiment_runs
parameters:
- in: query
name: workflow_id
schema:
anyOf:
- type: string
- type: 'null'
title: Workflow Id
required: false
- in: query
name: experiment_id
schema:
anyOf:
- type: string
- type: 'null'
title: Experiment Id
required: false
- in: query
name: block_id
schema:
anyOf:
- type: string
- type: 'null'
title: Block Id
required: false
- in: query
name: status
schema:
anyOf:
- enum:
- pending
- queued
- running
- completed
- error
- cancelled
type: string
- type: 'null'
title: Status
required: false
- in: query
name: exclude_status
schema:
anyOf:
- enum:
- pending
- queued
- running
- completed
- error
- cancelled
type: string
- type: 'null'
title: Exclude Status
required: false
- in: query
name: trigger_type
schema:
anyOf:
- type: string
- type: 'null'
title: Trigger Type
required: false
- in: query
name: from_date
schema:
anyOf:
- type: string
- type: 'null'
title: From Date
required: false
- in: query
name: to_date
schema:
anyOf:
- type: string
- type: 'null'
title: To Date
required: false
- in: query
name: sort_by
schema:
type: string
default: created_at
title: Sort By
required: false
- in: query
name: before
schema:
anyOf:
- type: string
- type: 'null'
title: Before
required: false
- in: query
name: after
schema:
anyOf:
- type: string
- type: 'null'
title: After
required: false
- in: query
name: limit
schema:
type: integer
maximum: 100
minimum: 1
default: 20
title: Limit
required: false
- in: query
name: order
schema:
enum:
- asc
- desc
type: string
default: desc
title: Order
required: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowExperimentRunList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
WorkflowExperimentRunList:
description: >-
A page of `WorkflowExperimentRun` resources. `data` holds the items and
`list_metadata` carries the `before`/`after` cursors; pass `after` to
fetch the next page.
properties:
data:
items:
$ref: '#/components/schemas/WorkflowExperimentRun'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: WorkflowExperimentRunList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
WorkflowExperimentRun:
properties:
id:
type: string
title: Id
workflow_id:
type: string
title: Workflow Id
workflow_version_id:
type: string
title: Workflow Version Id
trigger:
$ref: '#/components/schemas/ExperimentRunTrigger'
experiment_id:
type: string
title: Experiment Id
block_id:
type: string
title: Block Id
block_type:
type: string
enum:
- extract
- classifier
- split
- for_each
title: Block Type
n_consensus:
type: integer
enum:
- 3
- 5
- 7
title: N Consensus
lifecycle:
oneOf:
- $ref: '#/components/schemas/PendingWorkflowExperimentRun'
- $ref: '#/components/schemas/QueuedWorkflowExperimentRun'
- $ref: '#/components/schemas/RunningWorkflowExperimentRun'
- $ref: '#/components/schemas/CompletedWorkflowExperimentRun'
- $ref: '#/components/schemas/ErrorWorkflowExperimentRun'
- $ref: '#/components/schemas/CancelledWorkflowExperimentRun'
title: Lifecycle
discriminator:
propertyName: status
mapping:
cancelled:
$ref: '#/components/schemas/CancelledWorkflowExperimentRun'
completed:
$ref: '#/components/schemas/CompletedWorkflowExperimentRun'
error:
$ref: '#/components/schemas/ErrorWorkflowExperimentRun'
pending:
$ref: '#/components/schemas/PendingWorkflowExperimentRun'
queued:
$ref: '#/components/schemas/QueuedWorkflowExperimentRun'
running:
$ref: '#/components/schemas/RunningWorkflowExperimentRun'
timing:
$ref: '#/components/schemas/ExperimentRunTiming'
parent_run_id:
anyOf:
- type: string
- type: 'null'
title: Parent Run Id
block_version_id:
anyOf:
- type: string
- type: 'null'
title: Block Version Id
metrics_validity_fingerprint:
anyOf:
- type: string
- type: 'null'
title: Metrics Validity Fingerprint
metrics_validity_fingerprint_version:
anyOf:
- type: integer
- type: 'null'
title: Metrics Validity Fingerprint Version
block_execution_fingerprint:
type: string
title: Block Execution Fingerprint
documents_fingerprint:
type: string
title: Documents Fingerprint
score:
anyOf:
- type: number
- type: 'null'
title: Score
total_document_count:
type: integer
title: Total Document Count
default: 0
completed_document_count:
type: integer
title: Completed Document Count
default: 0
document_count:
type: integer
title: Document Count
default: 0
error_count:
type: integer
title: Error Count
default: 0
type: object
required:
- block_execution_fingerprint
- block_id
- block_type
- documents_fingerprint
- experiment_id
- id
- lifecycle
- n_consensus
- timing
- trigger
- workflow_id
- workflow_version_id
title: WorkflowExperimentRun
description: A single execution of an experiment, identified by `id`.
ListMetadata:
properties:
before:
anyOf:
- type: string
- type: 'null'
title: Before
after:
anyOf:
- type: string
- type: 'null'
title: After
type: object
required:
- after
- before
title: ListMetadata
description: Boundary resource IDs for page navigation.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
default: null
ctx:
type: object
title: Context
default: {}
type: object
required:
- loc
- msg
- type
title: ValidationError
ExperimentRunTrigger:
properties:
type:
anyOf:
- type: string
- type: 'null'
title: Type
type: object
title: ExperimentRunTrigger
PendingWorkflowExperimentRun:
properties:
status:
type: string
const: pending
title: Status
default: pending
type: object
title: PendingWorkflowExperimentRun
description: The experiment run has been created but execution has not started.
QueuedWorkflowExperimentRun:
properties:
status:
type: string
const: queued
title: Status
default: queued
type: object
title: QueuedWorkflowExperimentRun
description: The experiment run is enqueued and waiting for a worker.
RunningWorkflowExperimentRun:
properties:
status:
type: string
const: running
title: Status
default: running
type: object
title: RunningWorkflowExperimentRun
description: The experiment run is executing.
CompletedWorkflowExperimentRun:
properties:
status:
type: string
const: completed
title: Status
default: completed
type: object
title: CompletedWorkflowExperimentRun
description: The experiment run finished successfully.
ErrorWorkflowExperimentRun:
properties:
status:
type: string
const: error
title: Status
default: error
message:
type: string
title: Message
description: Human-readable error message
default: (no message)
details:
anyOf:
- $ref: '#/components/schemas/ErrorDetails'
- type: 'null'
description: Structured error context including stack trace
type: object
title: ErrorWorkflowExperimentRun
description: |-
The experiment run failed.
Carries a human-readable `message` and a structured `details` envelope
consumers can branch on instead of parsing free text.
CancelledWorkflowExperimentRun:
properties:
status:
type: string
const: cancelled
title: Status
default: cancelled
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
description: Human-readable reason, when known
type: object
title: CancelledWorkflowExperimentRun
description: >-
The experiment run was cancelled before reaching a natural terminal
state.
ExperimentRunTiming:
properties:
created_at:
type: string
format: date-time
title: Created At
description: When the experiment run record was created
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
completed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Completed At
duration_ms:
anyOf:
- type: integer
- type: 'null'
title: Duration Ms
type: object
title: ExperimentRunTiming
ErrorDetails:
properties:
message:
anyOf:
- type: string
- type: 'null'
title: Message
description: >-
Human-readable error message. Free-text; the structured fields below
are the machine-readable counterpart.
stack_trace:
anyOf:
- type: string
- type: 'null'
title: Stack Trace
description: Full stack trace
block_id:
anyOf:
- type: string
- type: 'null'
title: Block Id
description: ID of the block that failed
block_name:
anyOf:
- type: string
- type: 'null'
title: Block Name
description: Name/label of the block that failed
error_code:
anyOf:
- type: string
- type: 'null'
title: Error Code
description: Error code if available
context:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Context
description: Additional context about the error
type: object
title: ErrorDetails
description: |-
Detailed error information for debugging.
Captures stack traces and context about where and why an error occurred.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````