audit.workflow-run.get-history

Full transition log for one workflow run, after verifying it belongs to the caller's organization.

Return the full transition log for one workflow run, after verifying the run's organization_uuid matches the caller's.

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 caller's organization (run must belong to it)
workflow_uuid	string	Yes	—	The engine workflow id (UUID-shaped string) whose history is fetched
limit	integer	No	—	Page size (default 100, max 500, clamped by the engine)
offset	integer	No	—	Number of transition rows to skip from the start (default 0)
diagnostic_mode	boolean	No	—	When true, include the fuller redacted state_data_json payload for diagnostics
workflow_run_id	string	No	—	Engine-stamped parent DAG run id when invoked as a Step target

Output Schema

Field	Type	Required	Default	Description
workflow_uuid	string	Yes	—	Echo of the requested workflow_uuid
workflow_type	string	No	—	The run's workflow_type, or empty string if not found / org mismatch
items	json	Yes	—	Ordered list of state transitions for the run (oldest first). Each item: {state_name, is_terminal, terminal_status, actor, triggered_by, created_at_iso, state_data_json}. Empty if not found or the run belongs to another organization. state_data_json is a JSON-serialized string (not a dict): the engine's ReadOnlyDataWorkflow._strip_internal_ids walks every nested dict/list looking for unsibling'd id keys, but state_data is opaque JSON written by other workflows that may legitimately carry raw id columns from their own domain tables. Stringifying turns it into a scalar from the rule's perspective, so the audit surface doesn't have to opt those IDs into ALLOW_INTERNAL_IDS one library at a time. Clients should JSON.parse(state_data_json) to render.
total	integer	Yes	—	Total transition count for the run (independent of limit/offset)
limit	integer	Yes	—	Effective limit used by the query (after clamping)
offset	integer	Yes	—	Effective offset used by the query
mismatch	boolean	Yes	—	True if the run was not found OR belongs to another organization
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
read	SUCCESS	Workflow run history returned	workflow_uuid, items, total
failed	FAILURE	Audit workflow failed	failure_reason

API Usage

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

{
  "workflow_type": "audit.workflow-run.get-history",
  "initial_data": {
    "organization_uuid": "value",
    "workflow_uuid": "value"
  }
}