Skip to main content

API Reference

See the full request/response schema and parameters in the API Reference.

Run workflow

Execute a workflow and receive a job ID for tracking.
Runs use the workflow’s last valid saved definition.
To be notified when a run finishes, add an outgoing_webhook block to the workflow.

Idempotency-Key header (optional)

Send an Idempotency-Key header to make retries safe. It is scoped to your organization and the workflow, and names one run: a repeat request with the same key, at any later time, starts no new run and returns the original job_id with already_started: true and the run’s current status, such as running or completed. The body is not compared, so a repeat with different rows still returns the original run.

Request body (optional)

Unknown body keys are ignored. If webhook_payload is missing or misspelled, for example webhookPayload, the run processes the webhook block’s saved sample input instead of your rows, and it is billed.

Example request

For workflows that start from an uploaded file, pass the handle_id from Uploading an input file:

Response

status is uppercase RUNNING once the run has started. Live status reports lowercase statuses. already_started: true is added when an Idempotency-Key matched an earlier request. Use job_id to track the run. status can also be queued: the run is accepted but has not started yet. Track it with job_id as usual; repeating the request with the same Idempotency-Key returns this run instead of starting another. If webhook_payload cannot be stored in time, the request returns 503 and starts no run; see 503 Service Unavailable.
To run a workflow on a recurring cadence instead of calling Run Workflow manually, see Workflow Schedules.

List workflow runs

Get execution history for your workflows.
Runs are sorted most recent first (queued_at descending). Failed runs carry error_message and status_reason (null when no reason was recorded). metrics.workflow_cost_credits is what a run cost. When you may not see what the person who started it spent, the run is still listed, workflow_cost_credits is null, and spend_access says why. An API key sees the costs the person who created it may see.

Get live status

Monitor real-time progress of a running workflow.
run_id is the same as the job_id returned by Run Workflow.

Status values

queued, running, and finalizing are in progress. Every other status is final, including any status not listed here.

Polling recommendations

  • Poll every 10 seconds or slower.
  • Stop when overall_status is anything other than queued, running, or finalizing.
  • On 429 or 503, wait for Retry-After, then poll again; see Status polling.
  • Use overall_progress_percentage for progress bars.

Cancel run

Stop an in-progress workflow execution.
Pass job_id from the Run Workflow response as a query parameter. The response returns job_id, the run’s current status, and cancellation_requested. Until the run stops, the response can show queued or running with cancellation_requested: true:
Keep polling live status until overall_status is no longer queued, running, or finalizing. A terminal cancellation response is:
If the run had already finished, the API returns its final status without changes. Results produced before cancellation stay available.

Download results

Get download links for a run’s result files.
Request links once the run’s status is final. Failed and cancelled runs keep the files saved before they stopped. The response is a JSON array with one entry for each block that saved results:
  • The final result file comes from the workflow’s last block and is named {run_id}.csv ({run_id}.json or {run_id}.ndjson for those formats). It is the only file with the Status column described in Failed rows.
  • Every other entry is one block’s output, named {run_id}_{block_number}.csv (or .json or .ndjson).
Every result file starts with a _row_id column that numbers its rows from 1. Pass format=csv (default), format=json, or format=ndjson. JSON links exist only for runs started with save_json=true, and NDJSON links only for runs started with result_formats=ndjson. In workflow, search and Atlas CSV exports, list and object cells contain JSON; booleans are true or false. Parse list and object cells with json.loads() or JSON.parse(). Python’s ast.literal_eval() does not accept JSON null, true or false. Previously saved files keep their original text. Each download_url needs an x-api-key header from the run’s organization. Reuse it until it expires instead of requesting new links. While a step’s result files are still being saved, its CSV entry carries a message saying so, and its download_url and inline results already serve its rows. JSON and NDJSON link requests return 503 with a Retry-After header until the files are saved; see workflow result download retries. A run with a large result file can also finish later than usual while that file saves. Do not rerun the workflow. Link requests and file downloads each have an organization-wide budget; see Rate limits. For rate-limit responses and retry timing, see workflow result download retries.

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 and @northgate as '@northgate. Negative numbers such as -12.5 are unchanged. Every field is quoted, and the response carries an X-Spreadsheet-Safe: 1 header. To get the file exactly as stored, add ?spreadsheet_safe=false to the download_url. JSON and NDJSON files are never escaped. When code reads the results, request NDJSON with result_formats=ndjson.

Failed rows

A row fails at a step when that step still cannot process it after its retries. A failed row:
  • skips every later step and is not charged for those steps
  • stays in the output, with Failed in the columns the failing step would have filled
  • carries a _block_failed column in result files, set to the block_name of the step it failed at, such as lead_enrichment
  • is still sent to an outgoing webhook step
The final result 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 as is and the added column is named Workflow status. If that name is also taken, the added column uses the first available numbered name, starting with Workflow status 2. A run with some failed rows finishes as completed. It finishes as failed only when no row made it through the workflow. List workflow runs returns the counts in each run’s metrics: These fields are omitted when no row failed.

Example usage

Pricing

See Credit Costs for more information.