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 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,
)

{
  "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"
  }
}
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").
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,
)

{
  "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"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
workflow_id
string | null

Filter by workflow ID

​
status
enum<string> | null

Filter by run status

Available options:
pending,
queued,
running,
completed,
error,
failed,
awaiting_review,
cancelled
​
exclude_status
enum<string> | null

Exclude runs with this status

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

Filter by trigger type

Available options:
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_ms
integer | null

Filter runs with duration >= this value in milliseconds

​
max_duration_ms
integer | null

Filter runs with duration <= this value in milliseconds

​
search
string | null

Search by run ID (partial match)

​
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

Response

Successful Response

A page of WorkflowRun resources. data holds the items and list_metadata carries the before/after cursors; pass after to fetch the next page.

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

Boundary resource IDs for page navigation.