data.chat.engine.runs.get

Fetch a single workflow-engine run (by id) with optional transition history and child workflow ids, scoped to a (org, user) pair.

Fetch a single workflow-engine run by workflow_id.

Inputs (ADR-015):

• organization_uuid: Organization UUID (required, string).
• user_uuid: User UUID (required, string). Must be a member of organization_id or the call is rejected as unauthorized.
• workflow_uuid: The engine's external workflow id (required, string). Matched against WorkflowState.workflow_id scoped to organization_uuid.
• include_history: bool, default True. When False, history is returned as [].
• include_state_data: bool, default False. When False, each history entry's state_data is set to None (the field stays present for shape parity).

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

• workflow_uuid: Engine workflow UUID (str).
• workflow_type: Registered workflow type (e.g. "data.chat.x").
• project: Project tag for the run (str — derived from state_data.project when present, else "").
• status: "pending" | "running" | "completed" | "failed".
• current_state: Most recent state name.
• started_at: ISO-8601 timestamp of the earliest history row.
• ended_at: ISO-8601 timestamp of the terminal row, or None when the run is still in-flight.
• actor_uuid: Actor recorded on the first history row, or None if anonymous.
• input: Initial workflow input (state_data of the first history row).
• output: Terminal state_data (only when the run reached a terminal state, otherwise None).
• history: List of transition dicts (see below). Empty when include_history=False.
• child_workflow_uuids: List of child workflow UUID strings (DAG only; otherwise []).
• parent_workflow_uuid: Parent workflow UUID if this run is itself a DAG child, else None.

History entry shape::

{ "state_name": str, "entered_at": str (iso8601), "exited_at": str | null, # entered_at of the next row, or null # if this is the last row. "action": str | null, # state.triggered_by (best-effort). "transitioned_by": str | null, # state.actor "state_data": dict | null, # null when include_state_data=False "error": str | null, # state.terminal_reason on failure }

Failure vocabulary (raised as WorkflowBusinessError):

• organization_not_found_or_unauthorized — caller is not a member of the org (or the org/user UUID does not resolve). Returned BEFORE the run lookup so existence is never leaked.
• workflow_run_not_found — caller is authorized but the run id does not exist in this org.
• validation_failed — engine-level input validation rejected the request.

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	—	Engine's external workflow id (string form) for the run to fetch.
include_history	boolean	No	True	When True (default) include the transition history list. Set False to skip and receive history=[].
include_state_data	boolean	No	False	When False (default) each history entry's state_data is set to null to keep payloads small. Set True to include the full per-transition state_data dicts.

Output Schema

Field	Type	Required	Default	Description
workflow_uuid	uuid	Yes	—	Engine workflow id (public UUID for the run).
workflow_type	string	Yes	—	Registered workflow type.
project	string	Yes	—	Project tag for the run. Derived from state_data['project'] when present, else ''.
status	string	Yes	—	Coarse status: pending
current_state	string	Yes	—	Most recent state name.
started_at	string	Yes	—	ISO-8601 timestamp of the earliest history row.
ended_at	string	No	—	ISO-8601 timestamp of the terminal row, or null when still in-flight.
actor_uuid	uuid	No	—	Actor UUID from the first row, or null.
input	dict	Yes	—	Initial workflow input (first row state_data).
output	dict	No	—	Terminal state_data (only when the run is terminal, otherwise null).
history	list	Yes	—	Transition history; empty when include_history=False.
child_workflow_uuids	list	Yes	—	List of child workflow UUID strings if this run is a DAG parent, else [].
parent_workflow_uuid	uuid	No	—	Parent workflow UUID if this is a DAG child, else null.
error	string	No	—	Error message when the query failed (ReadOnlyDataWorkflow envelope hint).
error_type	string	No	—	Error class name when the query failed (ReadOnlyDataWorkflow envelope hint).

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.get",
  "initial_data": {
    "organization_uuid": "value",
    "user_uuid": "value",
    "workflow_uuid": "value"
  }
}