> ## 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 Runs
> List workflow runs with pagination and optional filters.
List workflow runs across one or more workflows. The endpoint supports id pagination plus a rich set of filters: by workflow, by status, by trigger type, by date range, by cost / duration, and by free-text run-ID search.
Pagination uses `before` / `after` cursors:
* Pass the **last** `id` from a page as `after` to get the next page.
* Pass the **first** `id` from a page as `before` to get the previous page.
Filter tips:
* `status` filters to a single run status (e.g. `"completed"`).
* `trigger_type` filters to a single trigger type (e.g. `"api"`).
* `from_date` / `to_date` accept either `YYYY-MM-DD` strings or Python `date` objects (the SDK serializes them).
* `fields` lets you slim the response down to just the keys you need (e.g. `"id,lifecycle,timing"`).
```python Python theme={null}
from datetime import date
from retab import Retab
client = Retab()
# All recent runs of a single workflow
runs = client.workflows.runs.list(
workflow_id="wf_abc123xyz",
limit=20,
order="desc",
sort_by="created_at",
)
# Failed runs in the last 7 days
recent_failures = client.workflows.runs.list(
workflow_id="wf_abc123xyz",
status="error",
from_date=date(2026, 4, 24),
to_date=date(2026, 5, 1),
limit=50,
)
# ID pagination — second page
next_page = client.workflows.runs.list(
workflow_id="wf_abc123xyz",
after=runs.list_metadata.after,
limit=20,
)
# Slim payload — IDs and statuses only
slim = client.workflows.runs.list(
workflow_id="wf_abc123xyz",
limit=100,
)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const runs = await client.workflows.runs.list({
workflowId: "wf_abc123xyz",
limit: 20,
order: "desc",
sortBy: "created_at",
});
const recentFailures = await client.workflows.runs.list({
workflowId: "wf_abc123xyz",
status: "error",
fromDate: "2026-04-24",
toDate: "2026-05-01",
limit: 50,
});
const nextPage = await client.workflows.runs.list({
workflowId: "wf_abc123xyz",
after: runs.list_metadata.after,
limit: 20,
});
```
```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.Runs.List(ctx, &retab.WorkflowRunsListParams{
PaginationParams: retab.PaginationParams{Limit: ptr(20), Order: ptr("desc")},
WorkflowID: ptr("wf_abc123xyz"),
SortBy: ptr("created_at"),
})
if err != nil {
log.Fatal(err)
}
recentFailures, err := client.Workflows.Runs.List(ctx, &retab.WorkflowRunsListParams{
PaginationParams: retab.PaginationParams{Limit: ptr(50)},
WorkflowID: ptr("wf_abc123xyz"),
Status: ptr(retab.WorkflowRunsStatus("error")),
FromDate: ptr("2026-04-24"),
ToDate: ptr("2026-05-01"),
})
if err != nil {
log.Fatal(err)
}
nextPage, err := client.Workflows.Runs.List(ctx, &retab.WorkflowRunsListParams{
PaginationParams: retab.PaginationParams{
After: ptr(runs.ListMetadata.After),
Limit: ptr(20),
},
WorkflowID: ptr("wf_abc123xyz"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(len(runs.Data), len(recentFailures.Data), len(nextPage.Data))
}
```
```ruby Ruby theme={null}
require 'retab'
require 'date'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
# All recent runs of a single workflow
runs = client.workflows.runs.list(
workflow_id: 'wf_abc123xyz',
limit: 20,
order: 'desc',
sort_by: 'created_at',
)
# Failed runs in the last 7 days
recent_failures = client.workflows.runs.list(
workflow_id: 'wf_abc123xyz',
status: 'error',
from_date: Date.new(2026, 4, 24),
to_date: Date.new(2026, 5, 1),
limit: 50,
)
# ID pagination — second page
next_page = client.workflows.runs.list(
workflow_id: 'wf_abc123xyz',
after: runs.list_metadata.after,
limit: 20,
)
```
```rust Rust theme={null}
use retab::enums::WorkflowRunsOrder;
use retab::resources::workflow_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().runs()
.list(ListParams {
workflow_id: Some("wf_abc123xyz".into()),
limit: Some(20),
order: Some(WorkflowRunsOrder::Desc),
sort_by: Some("created_at".into()),
..Default::default()
})
.await?;
let _recent_failures = client
.workflows().runs()
.list(ListParams {
workflow_id: Some("wf_abc123xyz".into()),
status: Some(retab::enums::WorkflowRunsStatus::Error),
from_date: Some("2026-04-24".into()),
to_date: Some("2026-05-01".into()),
limit: Some(50),
..Default::default()
})
.await?;
let _next_page = client
.workflows().runs()
.list(ListParams {
workflow_id: Some("wf_abc123xyz".into()),
after: runs.list_metadata.after.clone(),
limit: Some(20),
..Default::default()
})
.await?;
println!("{}", runs.data.len());
Ok(())
}
```
```php PHP theme={null}
workflows()->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.Runs.ListAsync(new WorkflowRunsListOptions());
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().runs().list("wf_abc123", null, null, null, null, null, null, null, null, null, null, null, 10L, null, "created_at");
System.out.println(result);
}
}
```
```curl cURL theme={null}
# All recent runs of one workflow
curl -X 'GET' \
'https://api.retab.com/v1/workflows/runs?workflow_id=wf_abc123xyz&limit=20&order=desc&sort_by=created_at' \
-H 'Authorization: Bearer '
# Status filter + date range
curl -X 'GET' \
'https://api.retab.com/v1/workflows/runs?workflow_id=wf_abc123xyz&status=error&from_date=2026-04-24&to_date=2026-05-01&limit=50' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"id": "run_abc123",
"workflow": {
"workflow_id": "wf_abc123xyz",
"version_id": "ver_abc123xyz"
},
"trigger": { "type": "api" },
"lifecycle": { "status": "completed" },
"timing": {
"created_at": "2026-05-01T14:30:00Z",
"started_at": "2026-05-01T14:30:00Z",
"completed_at": "2026-05-01T14:30:15Z"
},
"inputs": {
"documents": {
"start-1": {
"id": "file_123",
"filename": "invoice.pdf",
"mime_type": "application/pdf"
}
},
"json_data": {}
}
},
{
"id": "run_def456",
"workflow": {
"workflow_id": "wf_abc123xyz",
"version_id": "ver_abc123xyz"
},
"trigger": { "type": "api" },
"lifecycle": {
"status": "error",
"message": "Extract block failed: schema validation",
"stage": "execution",
"category": null,
"details": null,
"failing_step_id": "extract-block-1"
},
"timing": {
"created_at": "2026-05-01T13:55:00Z",
"started_at": "2026-05-01T13:55:00Z",
"completed_at": "2026-05-01T13:55:08Z"
},
"inputs": {
"documents": {
"start-1": {
"id": "file_456",
"filename": "scan_blurry.pdf",
"mime_type": "application/pdf"
}
},
"json_data": {}
}
}
],
"list_metadata": {
"before": "run_abc123",
"after": "run_def456"
}
}
```
## OpenAPI
````yaml GET /v1/workflows/runs
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows/runs:
get:
tags:
- Workflows
- Workflow Runs
summary: List Workflow Runs
description: List workflow runs with pagination and optional filters.
operationId: list_workflow_runs
parameters:
- in: query
name: workflow_id
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by workflow ID
title: Workflow Id
required: false
description: Filter by workflow ID
- in: query
name: status
schema:
anyOf:
- type: string
enum:
- pending
- queued
- running
- completed
- error
- failed
- awaiting_review
- cancelled
- type: 'null'
description: Filter by run status
title: Status
required: false
description: Filter by run status
- in: query
name: exclude_status
schema:
anyOf:
- type: string
enum:
- pending
- queued
- running
- completed
- error
- failed
- awaiting_review
- cancelled
- type: 'null'
description: Exclude runs with this status
title: Exclude Status
required: false
description: Exclude runs with this status
- in: query
name: trigger_type
schema:
anyOf:
- type: string
enum:
- manual
- api
- schedule
- webhook
- email
- restart
- type: 'null'
description: Filter by trigger type
title: Trigger Type
required: false
description: Filter by trigger type
- in: query
name: from_date
schema:
anyOf:
- type: string
- type: 'null'
description: Filter runs created on or after this date (YYYY-MM-DD)
title: From Date
required: false
description: Filter runs created on or after this date (YYYY-MM-DD)
- in: query
name: to_date
schema:
anyOf:
- type: string
- type: 'null'
description: Filter runs created on or before this date (YYYY-MM-DD)
title: To Date
required: false
description: Filter runs created on or before this date (YYYY-MM-DD)
- in: query
name: min_duration_ms
schema:
anyOf:
- type: integer
- type: 'null'
description: Filter runs with duration >= this value in milliseconds
title: Min Duration Ms
required: false
description: Filter runs with duration >= this value in milliseconds
- in: query
name: max_duration_ms
schema:
anyOf:
- type: integer
- type: 'null'
description: Filter runs with duration <= this value in milliseconds
title: Max Duration Ms
required: false
description: Filter runs with duration <= this value in milliseconds
- in: query
name: search
schema:
anyOf:
- type: string
- type: 'null'
description: Search by run ID (partial match)
title: Search
required: false
description: Search by run ID (partial match)
- description: >-
Filter by metadata equality: a JSON object of key/value pairs (e.g.
{"tenant":"acme"}). Pairs AND together.
in: query
name: metadata
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by metadata equality: a JSON object of key/value pairs
(e.g. {"tenant":"acme"}). Pairs AND together.
title: Metadata
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
description: Items per page
default: 20
title: Limit
required: false
description: Items per page
- in: query
name: order
schema:
enum:
- asc
- desc
type: string
default: desc
title: Order
required: false
- in: query
name: sort_by
schema:
type: string
default: timing.created_at
title: Sort By
required: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
WorkflowRunList:
description: >-
A page of `WorkflowRun` 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/WorkflowRun'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: WorkflowRunList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
WorkflowRun:
properties:
id:
type: string
title: Id
description: Unique ID for this run
workflow_id:
type: string
title: Workflow Id
description: ID of the workflow that was run
workflow_version_id:
type: string
title: Workflow Version Id
description: Content-addressed workflow version used for this run.
trigger:
$ref: '#/components/schemas/TriggerInfo'
description: What started this run
lifecycle:
oneOf:
- $ref: '#/components/schemas/PendingRun'
- $ref: '#/components/schemas/RunningRun'
- $ref: '#/components/schemas/AwaitingReviewRun'
- $ref: '#/components/schemas/CompletedTerminal'
- $ref: '#/components/schemas/ErrorTerminal'
- $ref: '#/components/schemas/CancelledTerminal'
title: Lifecycle
description: Lifecycle state of the run.
discriminator:
propertyName: status
mapping:
awaiting_review:
$ref: '#/components/schemas/AwaitingReviewRun'
cancelled:
$ref: '#/components/schemas/CancelledTerminal'
completed:
$ref: '#/components/schemas/CompletedTerminal'
error:
$ref: '#/components/schemas/ErrorTerminal'
pending:
$ref: '#/components/schemas/PendingRun'
running:
$ref: '#/components/schemas/RunningRun'
timing:
$ref: '#/components/schemas/RunTiming'
description: All timing information
inputs:
$ref: '#/components/schemas/RunInputs'
description: Input payloads supplied at run creation time
default:
documents: {}
json_data: {}
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Metadata
description: User-defined metadata associated with this workflow run.
type: object
required:
- id
- lifecycle
- timing
- trigger
- workflow_id
- workflow_version_id
title: WorkflowRun
description: A single execution of a workflow.
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
TriggerInfo:
properties:
type:
type: string
enum:
- manual
- api
- schedule
- webhook
- email
- custom
- restart
title: Type
description: What started this run
type: object
required:
- type
title: TriggerInfo
description: |-
Public summary of what started a run: just the trigger category.
The full per-variant detail (schedule_id, parent_run_id, sender, ...) is
kept internally on `StoredWorkflowRun.trigger` but intentionally not
exposed in the public API surface.
PendingRun:
properties:
status:
type: string
const: pending
title: Status
default: pending
type: object
title: PendingRun
description: The run has been created but execution has not started.
RunningRun:
properties:
status:
type: string
const: running
title: Status
default: running
type: object
title: RunningRun
description: The run is currently executing.
AwaitingReviewRun:
properties:
status:
type: string
const: awaiting_review
title: Status
default: awaiting_review
waiting_for_block_ids:
items:
type: string
type: array
title: Waiting For Block Ids
description: Block IDs that are waiting for review
default: []
type: object
title: AwaitingReviewRun
description: The run is paused on at least one gated block.
CompletedTerminal:
properties:
status:
type: string
const: completed
title: Status
default: completed
type: object
title: CompletedTerminal
description: The run finished successfully.
ErrorTerminal:
properties:
status:
type: string
const: error
title: Status
default: error
message:
type: string
title: Message
description: Human-readable error message
stage:
anyOf:
- type: string
enum:
- input_collection
- registry_lookup
- document_fetch
- execution
- output_storage
- routing
- history_payload
- type: 'null'
title: Stage
description: Which execution stage failed
category:
anyOf:
- type: string
enum:
- transient
- permanent
- quota
- type: 'null'
title: Category
description: Error category for retry decisions
details:
anyOf:
- $ref: '#/components/schemas/ErrorDetails'
- type: 'null'
description: Detailed error context including stack trace
failing_step_id:
anyOf:
- type: string
- type: 'null'
title: Failing Step Id
description: >-
Step ID of the failing step, when the failure was attributable to a
specific step
type: object
required:
- message
title: ErrorTerminal
description: The run failed. All loose error fields are bundled here.
CancelledTerminal:
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: CancelledTerminal
description: The run was cancelled before reaching a natural terminal state.
RunTiming:
properties:
created_at:
type: string
format: date-time
title: Created At
description: When the run record was created
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
description: When the run started executing
completed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Completed At
description: When the run finished executing
type: object
title: RunTiming
description: |-
Timing information for a run.
Three event timestamps that consumers cannot reconstruct on their own.
Wall-clock duration is a trivial `completed_at - started_at` subtraction
done client-side; it is not stored or exposed.
RunInputs:
properties:
documents:
additionalProperties:
$ref: '#/components/schemas/FileRef'
type: object
title: Documents
description: start_document block ID -> input document reference
default: {}
json_data:
additionalProperties: true
type: object
title: Json Data
description: start-json block ID -> input JSON data
default: {}
type: object
title: RunInputs
description: Input payloads supplied at run creation time.
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.
FileRef:
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: FileRef
description: Public/shared file reference used across SDK and customer-facing APIs.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````