Runs

A run is a single, end-to-end execution of a SuperPlane app. It begins when a trigger receives an event and ends when all connected actions have finished processing.

App run identity

Every run has a unique identity (a Run ID) that ties together all the activity triggered by a specific event. Instead of hunting through disparate logs, you can view a run as a single cohesive trace. A run tracks the initial payload, the path taken through the canvas, and the exact inputs and outputs of every node along the way.

Durable execution

SuperPlane uses a durable execution model. This means that workflow state is preserved across steps.

If a node crashes, times out, or the system restarts, the run does not lose its progress. Because every node’s payload is saved to the message chain, a workflow can safely pause and resume. This is critical for workflows that:

• Wait for human approval (which could take days).
• Call flaky external APIs that might need to be retried.
• Run long-running scripts on remote runners.

You don’t need to write custom retry logic or state-saving code; durable execution is built into the platform.

Run vs. node execution vs. queue item

To understand how SuperPlane processes work, it helps to distinguish between runs, node executions, and queue items:

• Run: The overarching execution of the entire canvas, triggered by a single event.
• Node execution: A specific action or trigger firing within the run. A single run contains many node executions.
• Queue item: The pending work for a node execution. When a node finishes, it pushes queue items to downstream nodes. SuperPlane workers pull these items from the queue to start the next node executions.

Version attachment

Every run is permanently attached to the canvas version that was active when the run started.

If you publish a new version of your app while a long-running workflow is still executing, the existing run will continue using the old version. This guarantees that workflows execute predictably, exactly as they were defined when the triggering event occurred.

State and result filters

Runs move through different states and conclude with a final result.

States:

• STATE_STARTED: The run is currently executing.
• STATE_FINISHED: The run has completed (regardless of success or failure).

Results:

• RESULT_PASSED: All node executions completed successfully.
• RESULT_FAILED: One or more node executions failed, and the run could not proceed.
• RESULT_CANCELLED: The run was manually aborted.

You can filter runs by these states and results in the UI or via the CLI to quickly find ongoing work or investigate failures.

Run inspection UI

The SuperPlane UI provides a dedicated view for inspecting runs. When you open an app, you can switch to the Runs tab to see a chronological list of all executions.

Bottom panel

Clicking on a specific run opens the bottom panel. This panel provides a detailed drill-down into the run’s history:

• Timeline: A chronological list of every node execution.
• Payloads: The exact JSON input and output for each step.
• Logs: Standard output and error logs generated by the nodes.

You can click on any node in the canvas while a run is selected to instantly filter the bottom panel to that specific node’s execution history.

Failure and error resolution

When a run fails (RESULT_FAILED), it stops executing downstream nodes. To resolve a failure:

1. Open the failed run in the UI.
2. Use the bottom panel to locate the specific node execution that failed.
3. Inspect the error logs and the input payload to determine why it failed (e.g., a bad API key, a malformed payload, or a network timeout).
4. Once you fix the underlying issue (e.g., updating a secret or fixing a bug in the canvas), you can often replay the failed node or restart the run, depending on the node’s configuration.

CLI and API usage

You can inspect runs directly from your terminal using the SuperPlane CLI.

List runs for an app:

superplane runs list --app-id <app_id>

Filter runs by state or result to find failures:

superplane runs list --app-id <app_id> --state STATE_STARTED --result RESULT_FAILED

Show full details for a specific run, including its node executions:

superplane runs describe <run_id> --app-id <app_id>

These commands wrap the SuperPlane API, which you can also call directly to integrate run monitoring into your own internal tools.