Running Flows
The Runs screen is where work actually happens: you start a flow against your inventory, watch it execute live, and read the results afterwards. The sidebar badge next to Runs counts runs that are currently active.

Start a run
Open Runs and click New Run (if the button is locked, your role lacks run-creation permission in this organization).
In Flow information, pick a flow by Name. The picker is searchable and lists pinned flows first, each with its version and description. This section holds only the flow and its version. Only committed flow versions can run - if the picker says Commit this flow before starting a run, open the flow in the editor and commit it first.
Pick a Version. One must be chosen before the run can start, and a flow you pick by hand never has one chosen for you: several committed versions are a decision. Switching versions clears any parameter values you already entered. Once a version with a form has loaded, Flow information folds away behind a one-line summary (Flow name · vN) so the form is in view; click its header to reopen it. Flows without a form keep the section open. Arriving through a Run button already answers both questions, so the page fills them in and Flow information starts folded: the flow's own Run button means its newest committed version, and Run this version means the one you clicked. Wherever a version is named - the dropdown and the folded summary - the newest committed one reads v3 (latest), so an older version is never mistaken for the current one.
Fill in Flow Parameters. This form is defined by the flow's author: required fields are marked with
*, and device-target fields open a picker where you can filter the inventory by site (optionally including child sites), inventory source, platform, vendor, and tags, then select devices individually or with Select all matching. The author can also place instruction notes in the form, such as what to check before you start. A note is only text to read: it is never sent with the run. A value may hold a template such as{{ run_id }}only if your role may edit the flow, and a template may not usesecret(),env()orfile()(see Templates in run inputs).The run name is generated for you and shown in the page header. Click the pencil next to it to rename the run before starting.
Click Start Run. You land on the run's detail page immediately.
To run the same thing on a schedule instead, create a schedule on the Triggers screen (Schedules tab) - see the schedules guide. Runs can also be started by webhooks, managed on the same screen.
Find runs
The run list filters on status, name, flow, and trigger kind. Filters, sort order, page, the active tab and how child runs are shown are all held in the address bar, so a filtered list can be bookmarked or pasted to a colleague and it opens the same way for them.
Links from the Home dashboard use this: each run tile opens the list filtered to exactly what the tile counted. Two of those bounds have no column to hang a filter widget on, so they appear above the table as chips that can be cleared on their own without losing the other filters:
- a trailing window on completion time (
since=24h), used by tiles that count a window such as failures in the last 24 hours; and - the actor who started the run (
by=<username>), used by the personal counts under Waiting on You.
An unfiltered list keeps a clean /runs URL - defaults are never written into the query string.
A link to a run from another tool should name the run's organization with ?org=<slug>, so it opens there whichever organization your browser last used - see Linking into an organization.
Runs that targeted a device
The API can list the runs that targeted one device, which is how a tool such as an inventory system shows a device's run history next to the device. GET /runs takes three filters for it:
target_provider_idandtarget_external_id- the device as its inventory provider knows it, for examplenetbox:primaryand the NetBox device id1042. The external id needs the provider id, since it is only unique within one provider.target_device_id- the device's Hegemony id.
They match the targets a run recorded when it started, so a run still matches by provider and external id after the device is renamed or deleted. target_device_id keeps matching after an ordinary delete, which only moves the device to the deleted list. A permanent delete clears the device link on the run's targets; after that the runs match by provider and external id only. The organization rules are unchanged: the list holds only runs the caller may read. A child run is listed when it targeted the device itself, with Subflow as its trigger; its parent is not listed through it, and a listed run does not bring its children along. Add top_level=true for top-level runs only.
GET /runs?target_provider_id=netbox:primary&target_external_id=1042&per_page=20Child runs
A flow's Run Flow step (flow.run) starts another flow as a child run, and a child can start children of its own. One action can start a dozen runs this way, so the list keeps them with the run that started them.
Child runs: Grouped, the default, lists top-level runs only: the runs no other run started. The pages, the count on the Active tab and every filter apply to top-level runs. To make room, the grouped list leaves out the Finished column; it still lists unfinished runs first, and the flat list shows the column. Each row adds Runs inside, a summary of every run below it however deep: a small bar split by status, and a line such as 16 child runs · all succeeded or 9 child runs · 1 failed. When a run below it failed, the row also says where the failure started, without opening anything - Failed in clm/deploy/linux-ansible › Verify served fingerprint is the flow of the run that failed first, and the step it failed in. A run waiting for an approval, or with a child run that is, says so too. A run waiting for its maintenance window says Waiting for maintenance window; hover over it, or focus it with the keyboard, to see the window's start and end, how long until it opens, and the node's message. In both the grouped and the flat list, the run's WAITING_WINDOW status badge shows the same on hover.
The arrow at the start of a row opens the run's tree in one framed group. Each child row shows its status, its flow and version, the step of its parent that started it (step Deploy), when it started counted from the top-level run (+0:42), its duration, and how many runs it holds in turn. A child with children of its own folds and unfolds on its own, and clicking a child row opens that run. Expand all and Collapse all open or close every group on the page. A tree loads when its group first opens; one holding more than 500 runs shows the first 500 and links to the run for the rest.
Child runs: Flat is the list one row per run, children included, with the parent run under Triggered By. Only the flat list offers the Subflow trigger filter, since no top-level run has a parent: switching to Grouped clears it, and a link that filters on it opens flat. The Deleted tab is always flat.
The choice is part of the address (children=flat), and your browser remembers it, so a plain /runs opens the way you last left it. The Home dashboard's run tiles count child runs too, so they open the flat list.
Read a run
The run detail page shows the flow name and version, what triggered the run (a user, a schedule, a webhook, or a parent flow), targets, timing, and five tabs:
- Graph - the flow diagram with each step colored by its execution state (pending, running, success, failed, skipped, cancelled, waiting). Fork and join nodes take the same colors for the whole run, however long it ran, and a join counts its arrived branches (2/3) until it fires. A running Sleep step shows the time left (3:46 left) and a bar that fills as the sleep passes; its detail panel adds the full length and the time it wakes up. Click a step to open its detail panel. Execution is what the run did: status, duration, worker, the tags the step carried when it ran, result data, error text, execution history for steps that ran more than once, and that step's live output. Configuration is what the step was told to do - the same fields the flow editor shows, read from the graph snapshot this run executed rather than from the flow as it stands today, so a failure can be read next to the settings that produced it however the flow has changed since. A step that never ran opens straight into its configuration. Notes the author placed on the flow canvas appear on the graph as plain text; they have no status and open no panel. Edges keep the routes the author drew in the editor: their bend points, and the ports the author moved on their nodes. Group and loop frames stay behind notes, notes stay behind connections, and nodes stay on top. Selecting a frame or note does not raise it over the execution graph.
- Logs - the merged, timestamped output stream of all steps. Filter by step or device, toggle stdout/stderr, timestamps, and line wrapping, and use Copy to grab the full log.
- Events - a milestone feed (step started/finished, decisions taken) without the raw container output. The first line says how the run started and who or what started it, for example Run started manually by alice, Run started by schedule 'Nightly backup', Run started by webhook 'Deploy hook' or Run started by parent flow 'Upgrade fleet' (run 'brave-otter', step 'Upgrade leaf'). The last line says how it ended: Run succeeded, Run failed: ... with the reason, or Run cancelled by alice. When the run ended at a terminal you renamed, the line names it, for example Run failed at terminal 'Rolled back'; the default Success and Failure terminals are not named, as the status already says it. A step that refused a host because its SSH host key is not trusted adds an entry for that host, marked with a red shield. When you know the host's key changed on purpose, accept the new key with Accept New Key on that entry. A host whose key may change, such as a lab's, can be exempted there too; its key changes then show as an entry with an amber shield. See SSH Host Keys.
- Artifacts - files and outputs collected by steps. Expand text artifacts in place, download individual files, or use the ZIP icon to download everything at once. Comparison artifacts show a diff with a Passed/Failed verdict: whether the comparison's expectation held, not whether the two sides are equal. The verdict names what was expected, so a comparison that must find a change reads Passed — changed as expected, and one that must find none reads Passed — no differences. When several outputs were compared, a list under the verdict shows each one with its own result, and a failed verdict names the outputs that failed. An output that did not change has no diff to show, so in a comparison that must find a change the list is where it appears. Each row carries a phase chip taken from the producing step's
phasetag, and no chip at all when that step has none. - Monitors - live charts for connectivity monitors attached to the run, with per-target statistics and a CSV export. See the connectivity monitor guide.
Runs stream their output live while the page is open - a green dot in the log toolbar means the stream is connected.
Platform administrators also get a Show Temporal identifiers toggle in the run header, revealing the workflow ID and Temporal run ID with copy buttons. They are correlation values for the workflow engine: paste them into tctl, or into the Temporal console on the rare occasion an administrator opens it. The page does not link to that console - it authenticates nobody and is scoped to no organization, so it stays closed and is opened deliberately from the host. See Temporal Admin Access.
Control a running run
While a run is active you can Pause it (if background monitors are running you will be asked whether to pause them too), Resume it, or Cancel it from the header. A paused run shows a banner with the pause message and, when the pause step defines one, a countdown until it resumes automatically. Each pause and resume appears in the Events tab with the name of the person who did it.
If a step requests human sign-off, the run enters waiting for approval and an amber card appears with a Review button - see the approvals guide.
Run again
Finished runs have a Re-run button that opens the New Run form pre-filled with the same flow version, parameters, and device targets, so you can adjust and start again in seconds. A run recorded without a version reruns with the flow filled in and the version left to you - it is not assumed to have been the newest. A value for a parameter the chosen version no longer has is left out when the run starts.
Delete and restore
Deleting a run from the list is reversible: it moves to the Deleted tab, where you can restore it or permanently delete it. Permanent deletion cannot be undone.
Over the API, GET /runs lists active runs. Add deleted_only=true for the Deleted tab's runs, or include_deleted=true for active and deleted runs together. GET /runs/filter-options takes the same two flags.
Statuses
| Status | Meaning |
|---|---|
PENDING | Queued, waiting for a worker to pick it up. |
RUNNING | Executing right now. |
PAUSED | Suspended by a pause step or by a user; resume from the banner. |
WAITING_APPROVAL | Blocked until someone approves or rejects. |
WAITING_WINDOW | Waiting for its maintenance window to open; move the window or start now from the banner. |
SUCCESS | Finished, every step succeeded. |
FAILED | Finished with a failed step; the header shows the error. |
CANCELLED | Stopped by a user before finishing. |