data.chat.engine.runs.summarize-failure

Structured failure summary for a workflow engine run, used by the chat layer to narrate failures without re-querying the engine.

Summarize a failed workflow engine run for chat-layer narration.

Inputs (ADR-015):

organization_id: Organization UUID (required, string).
user_id: User UUID (required, string). Must be a member of the organization or the call is rejected as unauthorized.
workflow_uuid: Workflow run identifier (required, string UUID). The engine stores this as the per-run id assigned at engine.start() time.

Outputs (ADR-015 — terminal state_data on success):

workflow_uuid: Echoed workflow UUID (str).
workflow_type: Registered workflow name (str, e.g. "user.onboarding").
status: One of "pending" | "running" | "completed" | "failed". Only "failed" produces meaningful summary fields; for other statuses summary fields are null.
failed_at: ISO-8601 timestamp of the failure (str | null).
failed_state: Name of the state that captured the failure (str | null).
failure_reason: Controlled-vocabulary reason from the engine (str | null).
error_group_ref: Lumen-correlated group id, if any (str | null). Note: Lumen ids are usually integer hashes server-side; we surface them as strings for shape stability.
error_group_count: How many times the same error pattern has occurred org-wide (int). 0 when unknown / Lumen unavailable.
related_runs: List of recent other runs hitting the same error_group_ref, capped at 5. Each entry: {workflow_uuid, workflow_type, failed_at (iso)}.
last_state_data: state_data at the moment of failure (dict | null). Truncated to <= 4096 bytes total JSON; when truncated, __truncated=True is set.
transition_chain: Ordered list of state names traversed before the failure (most recent last). Empty when the run is not in a failed status.

Failure vocabulary (raised as WorkflowBusinessError with stable codes):

organization_not_found_or_unauthorized
workflow_run_not_found
validation_failed

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 (string form)
`user_uuid`	uuid	Yes	—	User UUID (string form) — must be a member of the org
`workflow_uuid`	uuid	Yes	—	Workflow run identifier (string UUID)

Output Schema

Field	Type	Required	Default	Description
`workflow_uuid`	uuid	Yes	—	Echoed workflow id
`workflow_type`	string	Yes	—	Registered workflow name
`status`	string	Yes	—	One of "pending"
`failed_at`	string	No	—	ISO-8601 timestamp of the failure (null when not failed)
`failed_state`	string	No	—	Name of the state that captured the failure
`failure_reason`	string	No	—	Controlled-vocabulary reason from the engine
`error_group_ref`	string	No	—	Lumen-correlated group id (string form), or null
`error_group_count`	integer	Yes	—	Org-wide occurrence count of the same error pattern
`related_runs`	list	Yes	—	Other recent runs hitting the same error_group_ref (capped at 5)
`last_state_data`	dict	No	—	state_data at failure (truncated to <= 4096 bytes; sets __truncated=True when truncated)
`transition_chain`	list	Yes	—	Ordered state names traversed before failure (most recent last)
`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

bash

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

{
  "workflow_type": "data.chat.engine.runs.summarize-failure",
  "initial_data": {
    "organization_uuid": "value",
    "user_uuid": "value",
    "workflow_uuid": "value"
  }
}

data.chat.engine.runs.summarize-failure ​

Overview ​

Input Schema ​

Output Schema ​