run_workflow

run_workflow runs a saved workflow and reads back what it did. The action parameter selects the operation: start, status, explain, rows, or cancel.

start — run it now

Starts one run and returns its run_id at once; the run itself takes seconds to minutes.

Runs are a dry run by default.

In a dry run, reads run for real while every write — CRM, sequence enrollment, CSV — and every data lookup a dry run stands in for is mocked, so nothing changes. Start one yourself whenever it helps check the steps. A dry run reads every row its trigger would, with no cap; to try the steps on a few real rows first, use build_workflow’s preview_rows.

A live run (dry_run: false) needs the user’s explicit yes.

A live run writes what the workflow writes. The first live start runs nothing and returns confirmation_required: what it would start from and write, the last dry run’s counts, a user_facing_message, and a confirmation_token. Show the message, wait for an explicit yes, then start again with the same workflow_id, input_items, and trigger, plus the token.

One yes is one run: the token stops working once any run of the workflow starts, once it’s saved again, or after about 15 minutes.

A workflow may have several triggers; a run starts from one and runs only the steps after it (by default, the first that isn’t a webhook). Name another with trigger. A manual-trigger workflow starts from the rows of the external-data step right after it; pass input_items to use other rows for one run. A step that reads only what’s new continues where the last live run stopped; rewind: true on a dry run re-reads from where a first run would.

status — how far a run has got

Returns the run’s status (queued, running, then success, partial_success, error, canceled, timed_out, crashed, or skipped), how it started (mode, run_metadata), the step it’s at, and a per-step breakdown: rows in, rows out per side (by the side’s label), errors, and how each step ran. In a dry run, a stand-in step is flagged made_up — say so whenever you show its values. A step that acts once for all its rows (one CSV file, one email, a Slack message) reports did instead of a row count.

Poll until the status is no longer queued or running — each status call waits up to 15 seconds for the run to move on, and next says what to do.

explain — what a run did and why

The best place to start when the user asks what a run did or why something didn’t happen. For each step: its status, rows in and out per side, its own summary, the rows it turned away grouped by reason (turned_away), and the rows it kept grouped by reason (kept). Pass row (an example’s row, exactly as explain prints it) to trace one row’s whole path from where it came in — where a value went missing, which rule an if/switch turned it away on. examples sets how many rows each reason shows.

rows — the rows a step produced

Returns the rows a step sent out of one side (port, by its label; the main row-bearing side by default), paged by next_cursor, with a why per row where one applies and schema.labels naming every column in words — show those labels, never the raw keys. In a dry run, made_up flags which values are fabricated.

With download: true, every row of that side is saved as a dataset (private to your tenant, 7-day TTL) with a short inline preview — hand the user the download_dataset link to the CSV. Use it when there are more rows than are worth showing inline.

cancel — stop a run

Stops a queued or running run. Whatever its steps already wrote stays written.

Inputs

Parameter	Type	Required	Description
action	string	Yes	start, status, explain, rows, or cancel.
workflow_id	string	With start	The workflow to run.
run_id	string	With non-start	The run (returned by start).
dry_run	boolean	No	With start: true (default) changes nothing; false is a live run.
rewind	boolean	No	With a dry start: a step reading only what’s new re-reads from the start.
input_items	object[]	No	With start: rows for a manual or webhook run, this run only.
trigger	string	No	With start: the trigger to start from, in a workflow with several.
step	string	With rows	The step whose output to read, by its name.
port	string	No	With rows: that step’s side, by its label (its main side by default).
limit	integer	No	With rows: rows per page (1–200, default 20).
cursor	string	No	With rows: the previous page’s next_cursor.
row	string	No	With explain: an example’s row, to trace it back to the trigger.
examples	integer	No	With explain: example rows per reason (default 3).
download	boolean	No	With rows: save every row of the side as a downloadable dataset.
confirmation_token	string	With a live start	The token a confirmation_required answer gave, after the user said yes.
target_tenant_id	string	No	Super-tenant administrators only.

Notes

• Always confirm a live run with the user before passing dry_run: false with a token — the confirmation flow exists precisely because a live run touches the CRM, sequences, and files.
• Whenever you show a dry run’s output, say which values are stand-ins (made_up).