Skip to main content
GET
/
v1
/
workflows
/
runs
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 and pending runs in the last 7 days
recent_failures = client.workflows.runs.list(
    workflow_id="wf_abc123xyz",
    statuses=["error", "pending"],
    from_date=date(2026, 4, 24),
    to_date=date(2026, 5, 1),
    limit=50,
)

# Cursor 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",
    fields="id,lifecycle,timing",
    limit=100,
)

{
  "data": [
    {
      "id": "run_abc123",
      "organization_id": "org_123",
      "workflow": {
        "workflow_id": "wf_abc123xyz",
        "snapshot_id": "snap_abc123",
        "name_at_run_time": "Invoice Processing"
      },
      "trigger": { "type": "api" },
      "lifecycle": { "kind": "completed" },
      "timing": {
        "created_at": "2026-05-01T14:30:00Z",
        "started_at": "2026-05-01T14:30:00Z",
        "completed_at": "2026-05-01T14:30:15Z",
        "human_waiting_started_at": null,
        "accumulated_human_waiting_ms": 0,
        "duration_ms": 15000,
        "active_duration_ms": 15000
      },
      "inputs": {
        "documents": {
          "start-1": {
            "id": "file_123",
            "filename": "invoice.pdf",
            "mime_type": "application/pdf"
          }
        },
        "json_data": {}
      }
    },
    {
      "id": "run_def456",
      "organization_id": "org_123",
      "workflow": {
        "workflow_id": "wf_abc123xyz",
        "snapshot_id": "snap_def456",
        "name_at_run_time": "Invoice Processing"
      },
      "trigger": { "type": "api" },
      "lifecycle": {
        "kind": "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",
        "human_waiting_started_at": null,
        "accumulated_human_waiting_ms": 0,
        "duration_ms": 8000,
        "active_duration_ms": 8000
      },
      "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"
  }
}

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 runs across one or more workflows. The endpoint supports cursor 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 is single-valued; statuses accepts a comma-separated string or a list (e.g. "completed,error").
  • Same pattern for trigger_type (single) vs. trigger_types (multiple).
  • 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").
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 and pending runs in the last 7 days
recent_failures = client.workflows.runs.list(
    workflow_id="wf_abc123xyz",
    statuses=["error", "pending"],
    from_date=date(2026, 4, 24),
    to_date=date(2026, 5, 1),
    limit=50,
)

# Cursor 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",
    fields="id,lifecycle,timing",
    limit=100,
)

{
  "data": [
    {
      "id": "run_abc123",
      "organization_id": "org_123",
      "workflow": {
        "workflow_id": "wf_abc123xyz",
        "snapshot_id": "snap_abc123",
        "name_at_run_time": "Invoice Processing"
      },
      "trigger": { "type": "api" },
      "lifecycle": { "kind": "completed" },
      "timing": {
        "created_at": "2026-05-01T14:30:00Z",
        "started_at": "2026-05-01T14:30:00Z",
        "completed_at": "2026-05-01T14:30:15Z",
        "human_waiting_started_at": null,
        "accumulated_human_waiting_ms": 0,
        "duration_ms": 15000,
        "active_duration_ms": 15000
      },
      "inputs": {
        "documents": {
          "start-1": {
            "id": "file_123",
            "filename": "invoice.pdf",
            "mime_type": "application/pdf"
          }
        },
        "json_data": {}
      }
    },
    {
      "id": "run_def456",
      "organization_id": "org_123",
      "workflow": {
        "workflow_id": "wf_abc123xyz",
        "snapshot_id": "snap_def456",
        "name_at_run_time": "Invoice Processing"
      },
      "trigger": { "type": "api" },
      "lifecycle": {
        "kind": "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",
        "human_waiting_started_at": null,
        "accumulated_human_waiting_ms": 0,
        "duration_ms": 8000,
        "active_duration_ms": 8000
      },
      "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"
  }
}

Authorizations

​
Api-Key
string
header
required

Query Parameters

​
workflow_id
string | null

Filter by workflow ID

​
status
enum<string> | null

Filter by single run status (deprecated, use 'statuses')

Available options:
pending,
running,
completed,
error,
waiting_for_human,
cancelled
​
statuses
string | null

Filter by multiple statuses (comma-separated: pending,running,completed,error,waiting_for_human,cancelled)

​
exclude_status
enum<string> | null

Exclude runs with this status

Available options:
pending,
running,
completed,
error,
waiting_for_human,
cancelled
​
trigger_type
enum<string> | null

Filter by single trigger type (deprecated, use 'trigger_types')

Available options:
manual,
api,
schedule,
webhook,
email,
restart
​
trigger_types
string | null

Filter by multiple trigger types (comma-separated: manual,api,schedule,webhook,email,restart)

​
from_date
string | null

Filter runs created on or after this date (YYYY-MM-DD)

​
to_date
string | null

Filter runs created on or before this date (YYYY-MM-DD)

​
min_duration
integer | null

Filter runs with duration >= this value (milliseconds)

​
max_duration
integer | null

Filter runs with duration <= this value (milliseconds)

​
search
string | null

Search by run ID (partial match)

​
fields
string | null

Comma-separated list of persisted fields to return (e.g., 'id,lifecycle.kind,timing.started_at'). If not specified, returns all fields.

​
before
string | null
​
after
string | null
​
limit
integer
default:20

Items per page

Required range: 1 <= x <= 100
​
order
enum<string>
default:desc
Available options:
asc,
desc
​
sort_by
string
default:timing.created_at
​
access_token
string | null

Response

Successful Response

​
data
any[]
required
​
list_metadata
ListMetadata · object
required