The Execution API (POST /api/workflows/[id]/execute) is the primary entry point for triggering workflow runs within Sim Studio. It handles authentication, preprocessing, and routing to the core execution engine. This API supports synchronous JSON responses, real-time Server-Sent Events (SSE) streaming, and asynchronous background processing via job queues.
This page documents the technical implementation of the execution route, the request/response schemas, and the client-side hooks used to consume these streams.
The execution API serves as a unified gateway. Whether a workflow is started manually from the canvas, via an external API key, or through a scheduled trigger, it eventually routes through executeWorkflowCore.
The diagram below bridges the API request space to the core execution entities.
Execution Routing and Core Entities
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:5-13, apps/sim/app/api/workflows/[id]/execute/route.ts:42-59, apps/sim/app/api/workflows/[id]/execute/route.ts:234-255, apps/sim/lib/execution/preprocessing.ts1-20
The execution endpoint uses ExecuteWorkflowSchema (defined using Zod) to validate incoming payloads.
| Parameter | Type | Default | Description |
|---|---|---|---|
input | any | undefined | Data passed to the Start/Trigger block. |
stream | boolean | false | If true, returns a text/event-stream. |
useDraftState | boolean | false | Execute the current canvas draft instead of the deployed version. |
selectedOutputs | string[] | [] | Specific block outputs to include in the final response. |
runFromBlock | object | undefined | Configuration for partial re-execution starting from a specific node. |
stopAfterBlockId | string | undefined | Halts execution immediately after this block completes. |
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:76-116
The runFromBlock object allows for debugging by reusing cached states:
startBlockId: The ID where execution should resume. apps/sim/app/api/workflows/[id]/execute/route.ts:96-96sourceSnapshot: A SerializableExecutionState containing previous outputs and logs. apps/sim/app/api/workflows/[id]/execute/route.ts:97-112When stream: true is provided, the API returns a streaming response using createStreamingResponse. The server uses createExecutionEventWriter to buffer events and stream them as SSE.
Key Features:
block:started and block:completed events via createBlockEventHandlers. apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts:132-150stream:chunk events directly from AI providers to the client. apps/sim/lib/workflows/executor/execution-events.ts43-44DEFAULTS.MAX_SSE_CHILD_DEPTH). apps/sim/executor/handlers/workflow/workflow-handler.ts147-156Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:54-54, apps/sim/lib/execution/event-buffer.ts30 apps/sim/executor/handlers/workflow/workflow-handler.ts158-169
Used for simple API integrations. The server waits for executeWorkflowCore to resolve and returns the final ExecutionResult.
Sources: apps/sim/lib/workflows/executor/execution-core.ts42 apps/sim/app/api/workflows/[id]/execute/route.ts:42-42
Triggered via handleAsyncExecution. This enqueues a job in the background queue (Trigger.dev) and returns a 202 Accepted status with a jobId.
Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:187-218, apps/sim/background/workflow-execution.ts1-20
The frontend interacts with these APIs primarily through the useWorkflowExecution hook and the useExecutionStream utility.
useWorkflowExecution manages the local state of a running workflow, including terminal logs and visual "active" indicators on the canvas.
Client-to-Server Execution Sequence
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/hooks/use-workflow-execution.ts:104-162, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts:132-150
The processSSEStream function is the core utility for parsing the ReadableStream from the execution API. It handles:
execution:started, block:completed, etc., to provided callback functions. apps/sim/app/workspace/[workspaceId]/w/[workflowId]/utils/workflow-execution-utils.ts:132-150Workflows utilize a LoggingSession to track the lifecycle of an execution in the database.
LoggingSession is initialized with workflowId and executionId. apps/sim/lib/logs/execution/logging-session.ts37onBlockStart and onBlockComplete events are captured. BlockLog entries store duration and success status. apps/sim/executor/execution/block-executor.ts86-91 apps/sim/executor/execution/block-executor.ts172-180executeWorkflowCore finalizes the run, aggregating results and trace spans. apps/sim/lib/workflows/executor/execution-core.ts42The system aggregates BlockLog entries into a tree of trace spans. This powers the Terminal component in the UI.
useTerminalConsoleStore manages entries in real-time, handling updates for streaming outputs. apps/sim/stores/terminal/console/store.ts110-113Sources: apps/sim/executor/execution/block-executor.ts172-180 apps/sim/stores/terminal/console/store.ts26-55
The API implements several layers of error recovery and reporting:
createTimeoutAbortController to kill executions that exceed limits. apps/sim/app/api/workflows/[id]/execute/route.ts:9-13registerManualExecutionAborter allows users to stop a running execution. apps/sim/app/api/workflows/[id]/execute/route.ts:33-35handleBlockError in BlockExecutor captures the failure, calculates duration, and updates the BlockLog. apps/sim/executor/execution/block-executor.ts207-220Sources: apps/sim/app/api/workflows/[id]/execute/route.ts:33-35, apps/sim/executor/execution/block-executor.ts207-220
Refresh this wiki