audit.workflow-run.query

List workflow runs for an organization, filterable by workflow-type prefixes, state, terminal status, actor, and time range.

Paginated list of workflow runs for one organization, with optional domain-prefix scoping. Backed by engine storage; no side effects.

Overview

Property	Value
Workflow type	Atomic
Library	App-audit
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organization whose workflow runs are queried
workflow_type_prefixes	json	No	—	Optional list of workflow_type name prefixes (strings). A row matches if any prefix matches. Use to scope to a domain group, e.g. ['kubernetes.', 'k8s.', 'deploy.k8s.', 'runner.'].
workflow_type	string	No	—	Optional exact-match workflow type filter (less common than prefixes)
state_name	string	No	—	Optional filter on the current state's name (e.g. 'completed', 'failed')
is_terminal	boolean	No	—	If True, only terminal runs; if False, only non-terminal; omit for both
terminal_status	string	No	—	Optional filter: 'success' or 'failed'
actor	string	No	—	Optional filter on the actor (user/system identifier)
since	string	No	—	ISO 8601 timestamp; only runs created at or after this are returned
until	string	No	—	ISO 8601 timestamp; only runs created strictly before this are returned
limit	integer	No	—	Page size (default 50, max 500, clamped by the engine)
cursor	string	No	—	Opaque pagination token from a previous page's next_cursor. Round-trip it verbatim to fetch the next page; do not parse or fabricate it. Supersedes offset when supplied. Keyset-based, so deep pages stay cheap and page boundaries stay stable while new runs arrive.
offset	integer	No	—	DEPRECATED — number of rows to skip from the start (default 0). Kept for existing callers; prefer cursor, which supersedes it. Deep offsets re-scan everything they skip.
include_total	boolean	No	—	When true, also compute the exact matching-run count (an extra aggregate query). Default false: total comes back null and has_more/next_cursor still work, derived from an over-fetch of one row.
include_children	boolean	No	—	When true, DAG child/step executions are listed as first-class rows. Default false: only top-level runs (matches the aggregate workflow's default, so list and aggregate reconcile).
workflow_run_id	string	No	—	Engine-stamped parent DAG run id when invoked as a Step target

Output Schema

Field	Type	Required	Default	Description
items	json	Yes	—	List of workflow-run summaries. Each item: {workflow_uuid, workflow_type, state_name, is_terminal, terminal_status, actor, triggered_by, parent_workflow_uuid, workflow_run_uuid, step_name, created_at_iso}. state_data is deliberately omitted from the list view — fetch audit.workflow-run.get-history for the full payload of one run. Including state_data here blows the engine's nested output-item cap when k8s workflows (pod.list, deployment.list, …) carry large arrays in state_data.
total	integer	No	—	Exact distinct workflow_id count matching the filters, independent of pagination. Only computed when include_total=true (it re-runs the aggregate); null otherwise.
limit	integer	Yes	—	Effective limit used by the query (after clamping)
offset	integer	Yes	—	Effective offset used by the query (0 when a cursor was supplied)
has_more	boolean	Yes	—	Whether more rows exist beyond this page (derived from a one-row over-fetch)
next_cursor	string	No	—	Opaque token for the next page; pass it back as cursor. Null when has_more is false.
error	string	No	—	Set when the underlying storage call raised (string message)
error_type	string	No	—	Set when the underlying storage call raised (exception class name)

States

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

Outcomes

Outcome	Type	Description	State Data Keys
queried	SUCCESS	Workflow runs listed for the organization	items, total
failed	FAILURE	Audit workflow failed	failure_reason

API Usage

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

{
  "workflow_type": "audit.workflow-run.query",
  "initial_data": {
    "organization_uuid": "value"
  }
}