> ## 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 Workflow Eval Runs
> List workflow eval runs.
Optionally filter by `workflow_id`, `eval_id`, `target_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 workflow-eval runs, newest first. This is the run index for parent eval
runs, not the per-eval result history.
Filter by `workflow_id`, `eval_id`, `target_block_id`, lifecycle status,
trigger type, date range, or id pagination. `limit` defaults to 20, max 100.
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()
runs = client.workflows.evals.runs.list(
workflow_id="wf_abc123xyz",
status="completed",
limit=10,
)
for run in runs.data:
print(run.id, run.lifecycle.status, run.counts)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const runs = await client.workflows.evals.runs.list({
workflowId: "wf_abc123xyz",
status: "completed",
limit: 10,
});
for (const run of runs.data) {
console.log(run.id, run.lifecycle.status, run.counts);
}
```
```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)
}
runs, err := client.Workflows.Evals.Runs.List(ctx, &retab.WorkflowEvalRunsListParams{
WorkflowID: ptr("wf_abc123xyz"),
Status: ptr("completed"),
PaginationParams: retab.PaginationParams{
Limit: ptr(10),
},
})
if err != nil {
log.Fatal(err)
}
for _, run := range runs.Data {
fmt.Println(run.ID, run.Lifecycle.Status(), run.Counts)
}
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
runs = client.workflows.evals.runs.list(
workflow_id: 'wf_abc123xyz',
status: 'completed',
limit: 10,
)
runs.data.each do |run|
puts "#{run.id} #{run.lifecycle.status} #{run.counts}"
end
```
```rust Rust theme={null}
use retab::resources::workflow_eval_runs::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let runs = client
.workflows().evals().runs()
.list(ListParams {
workflow_id: Some("wf_abc123xyz".into()),
status: Some("completed".into()),
limit: Some(10),
..Default::default()
})
.await?;
for run in &runs.data {
println!("{} {:?} {:?}", run.id, run.lifecycle, run.counts);
}
Ok(())
}
```
```php PHP theme={null}
workflows()->evals()->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.Evals.Runs.ListAsync(new WorkflowEvalRunsListOptions());
Console.WriteLine(result);
```
```java Java theme={null}
import com.retab.RetabClient;
import com.retab.workflowevalruns.WorkflowEvalRunsApi;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = new WorkflowEvalRunsApi(client).list("wf_abc123", "eval_abc123", null, 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/evals/runs?workflow_id=wf_abc123xyz&status=completed&limit=10' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"id": "wfnodeevalrun_tRNzPiMpBas4kDwD74M8d",
"workflow_id": "wf_abc123xyz",
"workflow_version_id": "draft_2026_05_18",
"trigger": { "type": "api" },
"lifecycle": { "status": "completed" },
"timing": {
"created_at": "2026-05-18T10:00:00Z",
"started_at": "2026-05-18T10:00:01Z",
"completed_at": "2026-05-18T10:00:29Z",
"duration_ms": 28000
},
"eval_id": null,
"target": { "type": "block", "block_id": "block_extract_invoice" },
"total_evals": 4,
"counts": {
"lifecycle_counts": {
"pending": 0,
"queued": 0,
"running": 0,
"completed": 4,
"error": 0,
"cancelled": 0
},
"outcome": {
"passed": 3,
"failed": 1,
"blocked": 0
}
}
}
],
"list_metadata": {
"before": null,
"after": null
}
}
```
## OpenAPI
````yaml GET /v1/workflows/evals/runs
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows/evals/runs:
get:
tags:
- Workflows
- Workflow Eval Runs
summary: List Workflow Eval Runs
description: |-
List workflow eval runs.
Optionally filter by `workflow_id`, `eval_id`, `target_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_workflow_eval_runs
parameters:
- in: query
name: workflow_id
schema:
anyOf:
- type: string
- type: 'null'
title: Workflow Id
required: false
- in: query
name: eval_id
schema:
anyOf:
- type: string
- type: 'null'
title: Eval Id
required: false
- in: query
name: target_block_id
schema:
anyOf:
- type: string
- type: 'null'
title: Target Block Id
required: false
- in: query
name: status
schema:
anyOf:
- type: string
- type: 'null'
title: Status
required: false
- in: query
name: exclude_status
schema:
anyOf:
- 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
format: date-time
- type: 'null'
title: From Date
required: false
- in: query
name: to_date
schema:
anyOf:
- type: string
format: date-time
- 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: 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/WorkflowEvalRunList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
WorkflowEvalRunList:
description: >-
A page of `WorkflowEvalRun` 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/WorkflowEvalRun'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: WorkflowEvalRunList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
WorkflowEvalRun:
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/EvalRunTrigger'
lifecycle:
oneOf:
- $ref: '#/components/schemas/PendingWorkflowEvalRun'
- $ref: '#/components/schemas/QueuedWorkflowEvalRun'
- $ref: '#/components/schemas/RunningWorkflowEvalRun'
- $ref: '#/components/schemas/CompletedWorkflowEvalRun'
- $ref: '#/components/schemas/ErrorWorkflowEvalRun'
- $ref: '#/components/schemas/CancelledWorkflowEvalRun'
title: Lifecycle
discriminator:
propertyName: status
mapping:
cancelled:
$ref: '#/components/schemas/CancelledWorkflowEvalRun'
completed:
$ref: '#/components/schemas/CompletedWorkflowEvalRun'
error:
$ref: '#/components/schemas/ErrorWorkflowEvalRun'
pending:
$ref: '#/components/schemas/PendingWorkflowEvalRun'
queued:
$ref: '#/components/schemas/QueuedWorkflowEvalRun'
running:
$ref: '#/components/schemas/RunningWorkflowEvalRun'
timing:
$ref: '#/components/schemas/WorkflowEvalRunTiming'
target:
anyOf:
- $ref: '#/components/schemas/EvalRunBlockTarget'
- type: 'null'
eval_id:
anyOf:
- type: string
- type: 'null'
title: Eval Id
total_evals:
type: integer
title: Total Evals
counts:
$ref: '#/components/schemas/BlockEvalBatchExecutionCounts'
default:
lifecycle_counts:
cancelled: 0
completed: 0
error: 0
pending: 0
queued: 0
running: 0
outcome:
blocked: 0
failed: 0
passed: 0
freshness:
$ref: '#/components/schemas/EvalRunFreshness'
description: >-
Compatibility envelope only. WorkflowEval.freshness is the
authoritative read-time staleness verdict for saved eval
definitions.
type: object
required:
- id
- lifecycle
- timing
- total_evals
- trigger
- workflow_id
- workflow_version_id
title: WorkflowEvalRun
description: >-
A batch execution of a workflow's evals, with overall `lifecycle`,
`timing`, and pass/fail `counts`.
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
EvalRunTrigger:
properties:
type:
type: string
enum:
- manual
- api
- schedule
- webhook
- email
- custom
- restart
title: Type
type: object
required:
- type
title: EvalRunTrigger
PendingWorkflowEvalRun:
properties:
status:
type: string
const: pending
title: Status
default: pending
type: object
title: PendingWorkflowEvalRun
description: The eval run has been created but execution has not started.
QueuedWorkflowEvalRun:
properties:
status:
type: string
const: queued
title: Status
default: queued
type: object
title: QueuedWorkflowEvalRun
description: The eval run is enqueued and waiting for a worker.
RunningWorkflowEvalRun:
properties:
status:
type: string
const: running
title: Status
default: running
type: object
title: RunningWorkflowEvalRun
description: The eval run is executing assertions.
CompletedWorkflowEvalRun:
properties:
status:
type: string
const: completed
title: Status
default: completed
type: object
title: CompletedWorkflowEvalRun
description: The eval run finished. Per-eval verdicts live on each result row.
ErrorWorkflowEvalRun:
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: ErrorWorkflowEvalRun
description: |-
The eval run failed. The error message lives on this variant.
Carries the same structured `details` envelope as workflow runs so
consumers can branch on `error_code` / `stage` rather than parsing
a free-text message.
CancelledWorkflowEvalRun:
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: CancelledWorkflowEvalRun
description: The eval run was cancelled before reaching a natural terminal state.
WorkflowEvalRunTiming:
properties:
created_at:
type: string
format: date-time
title: Created At
description: When the workflow-eval run 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: WorkflowEvalRunTiming
EvalRunBlockTarget:
properties:
type:
type: string
const: block
title: Type
default: block
block_id:
type: string
title: Block Id
type: object
required:
- block_id
title: EvalRunBlockTarget
description: >-
Public workflow-eval target.
The storage layer remains block-scoped today, but the API shape names
the
tested entity explicitly so workflow-level targets can be added later.
BlockEvalBatchExecutionCounts:
properties:
lifecycle_counts:
$ref: '#/components/schemas/BlockEvalLifecycleCounts'
default:
pending: 0
queued: 0
running: 0
completed: 0
error: 0
cancelled: 0
outcome:
$ref: '#/components/schemas/BlockEvalOutcomeCounts'
default:
passed: 0
failed: 0
blocked: 0
type: object
title: BlockEvalBatchExecutionCounts
description: |-
Aggregate counts for a batch of block-eval runs.
Each individual run contributes to exactly one `lifecycle_counts`
bucket, and additionally to one `outcome` bucket when
`lifecycle_counts.completed` is incremented.
EvalRunFreshness:
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
required:
- baseline_run_id
- input_fingerprint
- validity_fingerprint
title: EvalRunFreshness
description: >-
Compatibility envelope on WorkflowEvalRun. This is not the authoritative
stale/fresh verdict for saved eval definitions; use
WorkflowEval.freshness for current staleness presentation.
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.
BlockEvalLifecycleCounts:
properties:
pending:
type: integer
title: Pending
default: 0
queued:
type: integer
title: Queued
default: 0
running:
type: integer
title: Running
default: 0
completed:
type: integer
title: Completed
default: 0
error:
type: integer
title: Error
default: 0
cancelled:
type: integer
title: Cancelled
default: 0
type: object
title: BlockEvalLifecycleCounts
description: Per-lifecycle counts for a batch of block-eval runs.
BlockEvalOutcomeCounts:
properties:
passed:
type: integer
title: Passed
default: 0
failed:
type: integer
title: Failed
default: 0
blocked:
type: integer
title: Blocked
default: 0
type: object
title: BlockEvalOutcomeCounts
description: Per-outcome counts. Only completed runs contribute to these buckets.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````