Run a workflow
SetWORKFLOW_ID to a workflow_id from List workflows. cURL also requires jq.
job_id.
HTTP 202
Parameters
Every body field is optional.
A run uses the workflow’s saved definition at the time it starts. A request with an unknown body field is refused with
422 and starts no run.
To be notified when a run finishes, add an
outgoing_webhook block to the workflow. To run a workflow on a recurring cadence, see Workflow Schedules.Idempotency-Key header
Send anIdempotency-Key header of up to 255 characters to make retries safe. A repeat request with the same key and the same body starts no new run and returns the original Job, even if the workflow was edited in between. The same key with a different body is refused with 409.
Check a run
PollGET /v1/jobs/{job_id} until status is succeeded, failed or canceled. Wait next_poll_after seconds between requests.
HTTP 200
List runs
GET /v1/jobs?workflow_id={workflow_id} returns a workflow’s runs, newest first. It also accepts status, page_size from 1 to 100 and cursor. See Browse Job history.
cURL
HTTP 200
Cancel a run
POST /v1/jobs/{job_id}/cancel asks a run to stop and returns the Job with cancel_requested_at. Keep polling until status is succeeded, failed or canceled: a run that finishes first keeps its own status.
cURL
HTTP 200
Download results
A finished Job lists its output files inresult, one per block and format. The file with the highest block_number is the workflow’s final output. Fetch a file from its download_url with your x-api-key header.
Every result file starts with a
_row_id column that numbers its rows from 1. In CSV files, list and object cells contain JSON, and booleans are true or false.
A failed or canceled Job has no result. For download rate limits, see Rate limits.
Spreadsheet-safe CSV
CSV downloads are escaped for spreadsheets by default. A cell that starts with=, +, -, @, a tab or a line break gets a leading ', so a spreadsheet shows it as text instead of running it as a formula. For example, +14155550123 downloads as '+14155550123. Negative numbers such as -12.5 are unchanged.
To get the file exactly as stored, add spreadsheet_safe=false to the download_url query string. NDJSON files are never escaped. When code reads the results, request NDJSON with result_formats.
Failed rows
A row fails at a block when that block still cannot process it after its retries. A failed row:- skips every later block and is not charged for those blocks
- stays in the output, with
Failedin the columns the failing block would have filled - carries a
_block_failedcolumn set to theblock_nameit failed at, such aslead_enrichment - is still sent to an outgoing webhook block
Status column set to Succeeded or Failed for each row. If your data already has a column named Status, it is kept and the added column is named Workflow status.
A run with some failed rows finishes as succeeded. It finishes as failed only when no row made it through the workflow.
Errors
For error responses, see Handling Errors.Pricing
See Credit Costs for more information.Integrations built on
/workflows/run, live_status and download-links keep working. See Workflow Execution (Legacy).