Workflow Runs And Statuses

Every workflow start creates a run. Runs snapshot the workflow definition, track each step, and keep enough detail to inspect, retry, rerun, and deliver output.

Run Start Kinds

Value	Meaning
`event`	Started by an integration event.
`schedule`	Started by a Dawn schedule event.
`manual`	Started by a person from the UI or API.
`agent`	Started by an agent/tool.
`one_off`	Started as a one-off workflow execution.

Run Statuses

Status	Meaning
`queued`	Run exists but a worker has not claimed it yet.
`running`	Run is actively executing or waiting for active steps.
`cancel_requested`	Cancellation has been requested but cleanup is not complete.
`completed`	Run completed successfully.
`failed`	Run ended with a failure. Inspect step errors and run error.
`canceled`	Run was canceled.

Active statuses are queued, running, and cancel_requested. Terminal statuses are completed, failed, and canceled.

Step Statuses

Status	Meaning
`queued`	Step is waiting for dependencies and worker execution.
`running`	Step is executing.
`completed`	Step completed.
`failed`	Step failed.
`canceled`	Step was canceled.
`skipped`	Step did not run because graph logic skipped it.

Step Outcome Kinds

Outcome	Meaning
`succeeded`	Step completed successfully.
`failed`	Step failed.
`canceled`	Step was canceled.
`condition_skipped`	A condition evaluated false.
`dependency_skipped`	A dependency was skipped, so this step was skipped too.
`dependency_failed`	A dependency failed, so this step could not run.
`graph_blocked`	The graph could not make progress.
`timed_out`	Step or run exceeded the allowed duration.

Use status for the broad lifecycle and outcomeKind for why a terminal step ended the way it did.

Run List Fields

GET /api/v1/workspaces/{workspaceId}/workflow-runs supports filtering by workflow, status, query, cursor, and limit.

The list response contains:

Field	Meaning
`items`	Current page of run summaries.
`nextCursor`	Cursor for the next page.
`hasMore`	Whether another page exists.
`totalCount`	Total count matching the current filters.

Run summary fields:

Field	Meaning
`id`	Run ID.
`workflowId`	Workflow definition ID.
`workflowName`	Workflow name at run time.
`startKind`	Why the run started.
`status`	Run status.
`provider`	Provider that started the run when event-triggered.
`eventType`	Event type when event-triggered.
`subjectTitle`	Human-readable subject.
`subjectUrl`	Provider subject URL when available.
`startedAt`	Start timestamp.
`completedAt`	Completion timestamp.
`durationMs`	Duration when known.
`error`	Run-level error when failed.
`createdAt`	Row creation timestamp.

Run Details Fields

GET /api/v1/workspaces/{workspaceId}/workflow-runs/{runId} returns the run summary plus:

Field	Meaning
`workspaceId`	Workspace ID.
`scopeKind`	Workflow scope, such as workspace or private.
`ownerUserId`	Owner for private workflows.
`triggerEventId`	Stored workflow event ID when event-triggered.
`startedByUserId`	User that manually started or reran the run.
`startedByAgentRunId`	Agent run that started this run when applicable.
`startedByWorkflowRunId`	Original run ID when this is a rerun.
`subjectKind`	Subject kind.
`subjectExternalId`	Provider subject ID/key.
`triggerEvent`	Normalized event JSON.
`manualInput`	Manual input JSON.
`definitionSnapshot`	Workflow definition snapshot used by this run.
`steps`	Step details.
`deliveries`	Delivery details.

Runs use a definition snapshot so historical run inspection does not change when the workflow definition is edited later.

Step Details Fields

Field	Meaning
`id`	Workflow run step ID.
`workflowStepId`	Definition step ID when present.
`order`	Step order.
`nodeKey`	Graph node key.
`dependsOn`	Dependency node keys.
`name`	Step name.
`stepType`	`agent_run` or `control`.
`agentRunId`	Child agent run ID for agent-run steps.
`conversationId`	Child conversation ID for agent-run steps.
`status`	Step status.
`outcomeKind`	Terminal outcome kind.
`input`	Step input JSON.
`outputText`	Text output.
`output`	Structured output JSON when available.
`startedAt`	Step start timestamp.
`completedAt`	Step completion timestamp.
`durationMs`	Step duration.
`error`	Step error.

Delivery Types

Delivery type	Purpose
`workspace_notification`	Workspace notification for terminal workflow output.
`personal_notification`	Personal notification target.
`monitor_notification`	Dawn Monitor notification surface.
`channel_result`	Channel result delivery target.
`slack_dm`	Slack direct message target.
`workflow_output_import`	Output imported into a Dawn thread.

Delivery status values are pending, delivering, delivered, and failed.

Delivery Details Fields

Field	Meaning
`id`	Delivery ID.
`deliveryType`	Delivery type.
`status`	Delivery status.
`deliveredAt`	Delivery timestamp when successful.
`lastError`	Last delivery error.
`targetConversationId`	Target Dawn conversation when applicable.
`targetMessageId`	Target Dawn message when applicable.
`targetAgentProfileId`	Target agent profile when applicable.
`targetExternalConversationId`	Target external conversation/thread when applicable.

Cancel, Rerun, Retry

Available run-control endpoints:

Endpoint	Purpose
`POST /workflow-runs/{runId}/cancel`	Cancel one active run.
`POST /workflow-runs/active/cancel`	Cancel active runs, optionally for one workflow.
`POST /workflow-runs/{runId}/rerun`	Create a new run with the same workflow and subject/input context.
`POST /workflow-runs/{runId}/steps/{runStepId}/retry`	Reset a failed terminal step and its dependents for another attempt.
`DELETE /workflow-runs/{runId}`	Delete one finished run.
`DELETE /workflow-runs/finished`	Delete finished runs, optionally by workflow or status.

Rerun creates a new run. Step retry reuses the same run and resets the chosen step plus dependent steps. Retrying a step that was skipped only makes sense when its blockers are also reset or already successful.

Output Delivery

Completed workflow output can be imported into Dawn threads:

Endpoint	Purpose
`POST /workflow-runs/{runId}/deliver-current-thread`	Import output into an existing conversation.
`POST /workflow-runs/{runId}/deliver-new-thread`	Create a new thread and import output.

Request fields:

Field	Meaning
`targetConversationId`	Existing conversation for current-thread delivery.
`stepId`	Optional step whose output should be delivered.
`outputText`	Optional explicit output text.
`includeAllStepOutputs`	Include output from all steps instead of only the selected/final step.

Use output delivery to move automated work into a human discussion without requiring every workflow result to create a chat thread automatically.