Skip to main content
Each run of a workflow is a Job. Start it, poll it and cancel it with the same requests you use for every other Job.

Run a workflow

Set WORKFLOW_ID to a workflow_id from List workflows. cURL also requires jq.
The response is a Job. Keep its 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 an Idempotency-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

Poll GET /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
A run that already finished is unchanged, and completed work remains billed.

Download results

A finished Job lists its output files in result, 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 Failed in the columns the failing block would have filled
  • carries a _block_failed column set to the block_name it failed at, such as lead_enrichment
  • is still sent to an outgoing webhook block
The final output file ends with a 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).