> ## 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 Experiments
> List experiments under one workflow with cursor pagination.
Optionally filter by `block_id`. Each experiment is returned with its
latest-run snapshot, block info, and drift detection.
List all experiments attached to a workflow, with the latest run's
status, score, staleness flag, and schema-drift state.
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.list(workflow_id="wf_abc123")
for exp in page.data:
print(exp.id, exp.name, exp.status, exp.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.list({ workflowId: "wf_abc123" });
for (const exp of page.data) {
console.log(exp.id, exp.name, exp.status, exp.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.List(ctx, &retab.WorkflowExperimentsListParams{
WorkflowID: "wf_abc123",
})
if err != nil {
log.Fatal(err)
}
for _, exp := range page.Data {
fmt.Println(exp.ID, exp.Name, exp.Status, exp.Score)
}
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
page = client.workflows.experiments.list(workflow_id: 'wf_abc123')
page.data.each do |exp|
puts "#{exp.id} #{exp.name} #{exp.status} #{exp.score}"
end
```
```rust Rust theme={null}
use retab::resources::workflow_experiments::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()
.list(ListParams::new("wf_abc123"))
.await?;
for exp in &page.data {
println!("{} {} {:?} {:?}", exp.id, exp.name, exp.status, exp.score);
}
Ok(())
}
```
```php PHP theme={null}
workflows()->experiments()->list(
workflowId: 'wf_abc123',
);
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.ListAsync(new WorkflowExperimentsListOptions());
Console.WriteLine(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().list("wf_abc123", null, null, null, 10L, null);
System.out.println(result);
}
}
```
```curl cURL theme={null}
curl -X 'GET' \
'https://api.retab.com/v1/workflows/experiments?workflow_id=wf_abc123' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"id": "exp_abc",
"workflow_id": "wf_abc123",
"block_id": "extract-invoice",
"block_kind": "extract",
"n_consensus": 5,
"document_count": 12,
"name": "Q1 invoices",
"last_run_id": "exprun_1",
"status": "completed",
"score": 0.87,
"is_stale": false,
"schema_drift": "none",
"schema_drift_detail": null,
"created_at": "2026-05-01T14:30:00Z",
"updated_at": "2026-05-02T09:00:00Z"
}
],
"list_metadata": {
"before": null,
"after": null
}
}
```
## OpenAPI
````yaml GET /v1/workflows/experiments
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows/experiments:
get:
tags:
- Workflows
- Workflow Experiments
summary: List Experiments
description: |-
List experiments under one workflow with cursor pagination.
Optionally filter by `block_id`. Each experiment is returned with its
latest-run snapshot, block info, and drift detection.
operationId: list_experiments
parameters:
- in: query
name: workflow_id
required: true
schema:
type: string
title: Workflow Id
- in: query
name: block_id
schema:
anyOf:
- type: string
- type: 'null'
title: Block Id
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: 50
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/WorkflowExperimentList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
WorkflowExperimentList:
description: >-
A page of `WorkflowExperiment` 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/WorkflowExperiment'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: WorkflowExperimentList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
WorkflowExperiment:
properties:
id:
type: string
title: Id
workflow_id:
type: string
title: Workflow Id
block_id:
type: string
title: Block Id
n_consensus:
type: integer
enum:
- 3
- 5
- 7
title: N Consensus
document_count:
type: integer
title: Document Count
default: 0
name:
type: string
title: Name
last_run_id:
anyOf:
- type: string
- type: 'null'
title: Last Run Id
created_at:
type: string
format: date-time
title: Created At
description: When the experiment was created
updated_at:
type: string
format: date-time
title: Updated At
description: When the experiment was last updated
status:
type: string
enum:
- draft
- processing
- completed
- failed
- cancelled
title: Status
default: draft
block_type:
type: string
enum:
- extract
- classifier
- split
- for_each
title: Block Type
score:
anyOf:
- type: number
- type: 'null'
title: Score
is_stale:
type: boolean
title: Is Stale
default: false
freshness:
$ref: '#/components/schemas/ArtifactFreshness'
freshness_state:
type: string
enum:
- fresh
- stale
- unknown
title: Freshness State
default: unknown
freshness_reasons:
items:
type: string
type: array
title: Freshness Reasons
default: []
run_plan_mode:
type: string
enum:
- run
- noop
- conflict
- unknown
title: Run Plan Mode
default: unknown
rerunnable_document_count:
type: integer
title: Rerunnable Document Count
default: 0
schema_drift:
type: string
enum:
- none
- partial
- drifted
- unknown
title: Schema Drift
default: unknown
schema_drift_detail:
anyOf:
- type: string
- type: 'null'
title: Schema Drift Detail
drift:
$ref: '#/components/schemas/ArtifactDrift'
type: object
required:
- block_id
- block_type
- id
- n_consensus
- name
- workflow_id
title: WorkflowExperiment
description: >-
An experiment that evaluates a workflow block against a set of
documents, with its latest run status and score.
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
ArtifactFreshness:
properties:
status:
type: string
enum:
- fresh
- stale
- unknown
title: Status
default: unknown
reasons:
items:
type: string
enum:
- validity_changed
- inputs_changed
- engine_changed
- metrics_engine_changed
- no_baseline
type: array
title: Reasons
default: []
validity_fingerprint:
anyOf:
- type: string
- type: 'null'
title: Validity Fingerprint
input_fingerprint:
anyOf:
- type: string
- type: 'null'
title: Input Fingerprint
baseline_run_id:
anyOf:
- type: string
- type: 'null'
title: Baseline Run Id
type: object
title: ArtifactFreshness
ArtifactDrift:
properties:
status:
type: string
enum:
- none
- drifted
- broken
- unknown
title: Status
default: unknown
affected_targets:
items:
type: string
type: array
title: Affected Targets
default: []
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: ArtifactDrift
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````