data.chat.engine.runs.list

Paginated list of workflow-engine runs for the caller's org

Paginated list of workflow-engine runs scoped to a (org, user) pair.

Reads the engine's own workflow_states table — one entry per workflow run, derived from the latest state row per workflow_id. started_at is the first row's created_at and ended_at is the latest row's created_at when terminal.

Overview

Property	Value
Workflow type	Atomic
Library	App-chat
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization UUID — scopes runs to org-owned rows
user_uuid	uuid	Yes	—	User UUID — auth check (not a row filter)
project	string	No	—	Optional project slug, e.g. 'ltinteg-api-core'
workflow_type	string	No	—	Exact workflow_type match; takes precedence over prefix
workflow_type_prefix	string	No	—	Prefix match on workflow_type, e.g. 'agents.'
status	string	No	—	One of pending
since	string	No	—	ISO 8601 lower bound on started_at
until	string	No	—	ISO 8601 upper bound on started_at
actor_uuid	uuid	No	—	Optional actor UUID filter (matches WorkflowState.actor)
cursor	string	No	—	Opaque pagination cursor from a previous page
limit	integer	No	25	Page size (1..100, default 25)

Output Schema

Field	Type	Required	Default	Description
runs	list	Yes	—	Engine run dicts sorted by started_at DESC
next_cursor	string	No	—	Cursor for the next page, or null when exhausted
summary	dict	Yes	—	{total, by_status:{pending,running,completed,failed}}
error	string	No	—	Error message when query failed
error_type	string	No	—	Error class name when query failed

States

State	Initial	Terminal	Success	Auto-advance	Description
done	Yes	Yes	Yes	—	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "data.chat.engine.runs.list",
  "initial_data": {
    "organization_uuid": "value",
    "user_uuid": "value"
  }
}