> ## 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 Results
> List per-document results for an experiment run.
Requires the `run_id` query parameter. Returns one result row per document
in the run, with each row's lifecycle status, timing, and produced
artifact, as a cursor-paginated list.
List per-document results for one experiment run. Filter by `run_id`; each result also has its own
opaque `id`; use [Get Experiment Run Result](/api-reference/workflows/experiments/results/get)
to refresh one row directly.
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()
results = client.workflows.experiments.results.list("exprun_2")
for result in results.data:
print(result.document_id, result.lifecycle.status, result.artifact)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const results = await client.workflows.experiments.results.list({
runId: "exprun_2",
});
for (const result of results.data) {
console.log(result.documentId, result.lifecycle.status, result.artifact);
}
```
```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)
}
results, err := client.Workflows.Experiments.Results.List(ctx, &retab.ExperimentRunResultsListParams{
RunID: "exprun_2",
PaginationParams: retab.PaginationParams{
Limit: ptr(20),
},
})
if err != nil {
log.Fatal(err)
}
for _, result := range results.Data {
fmt.Println(result.DocumentID, result.Lifecycle.Status(), result.Artifact)
}
}
```
```rust Rust theme={null}
use retab::resources::experiment_run_results::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let results = client
.workflows().experiments().results()
.list(ListParams::new("exprun_2"))
.await?;
for result in &results.data {
println!(
"{} {:?} {:?}",
result.document_id, result.lifecycle, result.artifact
);
}
Ok(())
}
```
```php PHP theme={null}
workflows()->experiments()->results()->list(
runId: 'run_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.Results.ListAsync(new ExperimentRunResultsListOptions());
Console.WriteLine(result);
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
result = client.workflows.experiments.results.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().results().list("run_abc123", null, null, 10L, null);
System.out.println(result);
}
}
```
```curl cURL theme={null}
curl -X 'GET' \
'https://api.retab.com/v1/workflows/experiments/results?run_id=exprun_2&limit=20' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"id": "expresult_1",
"run_id": "exprun_2",
"experiment_id": "exp_abc",
"document_id": "expdoc_xyz",
"block_kind": "extract",
"lifecycle": { "status": "completed" },
"timing": {
"started_at": "2026-05-02T11:00:01Z",
"completed_at": "2026-05-02T11:00:05Z",
"duration_ms": 4120
},
"handle_inputs": {
"input-document-0": { "type": "file", "filename": "invoice_q1.pdf" }
},
"artifact": { "operation": "extraction", "id": "ext_xyz" },
"attempt": 0
}
],
"list_metadata": {
"before": null,
"after": null
}
}
```
## OpenAPI
````yaml GET /v1/workflows/experiments/results
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows/experiments/results:
get:
tags:
- Workflows
- Workflow Experiments
summary: List Experiment Results
description: >-
List per-document results for an experiment run.
Requires the `run_id` query parameter. Returns one result row per
document
in the run, with each row's lifecycle status, timing, and produced
artifact, as a cursor-paginated list.
operationId: list_experiment_results
parameters:
- in: query
name: run_id
required: true
schema:
type: string
title: Run Id
- 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: 1000
minimum: 1
default: 100
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/WorkflowExperimentResultList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
WorkflowExperimentResultList:
description: >-
A page of `WorkflowExperimentResult` 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/WorkflowExperimentResult'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: WorkflowExperimentResultList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
WorkflowExperimentResult:
properties:
id:
type: string
title: Id
experiment_run_id:
type: string
title: Experiment Run Id
experiment_id:
type: string
title: Experiment Id
document_id:
type: string
title: Document Id
lifecycle:
oneOf:
- $ref: '#/components/schemas/PendingWorkflowExperimentResult'
- $ref: '#/components/schemas/QueuedWorkflowExperimentResult'
- $ref: '#/components/schemas/RunningWorkflowExperimentResult'
- $ref: '#/components/schemas/CompletedWorkflowExperimentResult'
- $ref: '#/components/schemas/ErrorWorkflowExperimentResult'
- $ref: '#/components/schemas/CancelledWorkflowExperimentResult'
title: Lifecycle
discriminator:
propertyName: status
mapping:
cancelled:
$ref: '#/components/schemas/CancelledWorkflowExperimentResult'
completed:
$ref: '#/components/schemas/CompletedWorkflowExperimentResult'
error:
$ref: '#/components/schemas/ErrorWorkflowExperimentResult'
pending:
$ref: '#/components/schemas/PendingWorkflowExperimentResult'
queued:
$ref: '#/components/schemas/QueuedWorkflowExperimentResult'
running:
$ref: '#/components/schemas/RunningWorkflowExperimentResult'
timing:
$ref: '#/components/schemas/ExperimentResultTiming'
block_type:
type: string
enum:
- extract
- classifier
- split
- for_each
title: Block Type
handle_inputs:
additionalProperties:
oneOf:
- $ref: '#/components/schemas/JsonHandleInput'
- $ref: '#/components/schemas/FileHandleInput'
discriminator:
propertyName: type
mapping:
file:
$ref: '#/components/schemas/FileHandleInput'
json:
$ref: '#/components/schemas/JsonHandleInput'
type: object
title: Handle Inputs
default: {}
handle_outputs:
additionalProperties:
oneOf:
- $ref: '#/components/schemas/JsonHandleInput'
- $ref: '#/components/schemas/FileHandleInput'
discriminator:
propertyName: type
mapping:
file:
$ref: '#/components/schemas/FileHandleInput'
json:
$ref: '#/components/schemas/JsonHandleInput'
type: object
title: Handle Outputs
default: {}
artifact:
anyOf:
- $ref: '#/components/schemas/StepArtifactRef'
- type: 'null'
attempt:
type: integer
title: Attempt
default: 0
type: object
required:
- block_type
- document_id
- experiment_id
- experiment_run_id
- id
- lifecycle
- timing
title: WorkflowExperimentResult
description: >-
One experiment block execution for a single document, addressed by
`experiment_run_id` and `document_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
PendingWorkflowExperimentResult:
properties:
status:
type: string
const: pending
title: Status
default: pending
type: object
title: PendingWorkflowExperimentResult
description: The result row has been created but execution has not started.
QueuedWorkflowExperimentResult:
properties:
status:
type: string
const: queued
title: Status
default: queued
type: object
title: QueuedWorkflowExperimentResult
description: The result row is enqueued and waiting for a worker.
RunningWorkflowExperimentResult:
properties:
status:
type: string
const: running
title: Status
default: running
type: object
title: RunningWorkflowExperimentResult
description: The result row is executing.
CompletedWorkflowExperimentResult:
properties:
status:
type: string
const: completed
title: Status
default: completed
type: object
title: CompletedWorkflowExperimentResult
description: The result row finished successfully.
ErrorWorkflowExperimentResult:
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: ErrorWorkflowExperimentResult
description: The result row failed. Per-job error message is bundled into lifecycle.
CancelledWorkflowExperimentResult:
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: CancelledWorkflowExperimentResult
description: >-
The result row was cancelled (typically propagated from a cancelled
run).
ExperimentResultTiming:
properties:
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
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: ExperimentResultTiming
JsonHandleInput:
properties:
type:
type: string
const: json
title: Type
default: json
data:
title: Data
default: null
additionalProperties: false
type: object
title: JsonHandleInput
description: JSON payload for a handle input. `data` is the raw JSON value.
FileHandleInput:
properties:
type:
type: string
const: file
title: Type
default: file
document:
$ref: '#/components/schemas/ResultFileRef'
additionalProperties: false
type: object
required:
- document
title: FileHandleInput
description: File reference for a handle input.
StepArtifactRef:
properties:
operation:
type: string
enum:
- extraction
- split
- classification
- parse
- edit
- partition
- conditional_evaluation
- review_trigger_evaluation
- while_loop_termination
- api_call_invocation
- function_invocation
title: Operation
description: The kind of resource this artifact references
id:
type: string
title: Id
description: Resource identifier
type: object
required:
- id
- operation
title: StepArtifactRef
description: >-
A resource produced by a workflow step.
An `(operation, id)` reference. The artifact itself carries no payload —
consumers dispatch on `operation` and fetch the referenced record by
`id`.
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.
ResultFileRef:
properties:
id:
type: string
title: Id
description: ID of the file
filename:
type: string
title: Filename
description: Filename of the file
mime_type:
type: string
title: Mime Type
description: MIME type of the file
type: object
required:
- filename
- id
- mime_type
title: ResultFileRef
description: Public/shared file reference used across SDK and customer-facing APIs.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````