Core concepts
Execution flow
- List workflows to find the
workflow_idyou want to run. - Run the workflow with input rows and receive a Job.
- Poll the Job until
statusissucceeded,failedorcanceled. - Download the output files listed in the Job’s
result.
Run a workflow
ReplaceYOUR_API_KEY with your API key and WORKFLOW_ID with a workflow_id from the list. cURL uses jq; Python uses requests; JavaScript uses Node.js 18 or later.
List workflows
HTTP 200
Start a run
Send the rows ininput, one object per row. input applies to workflows whose first block is Incoming Webhooks. For a workflow that reads a file, see Run on an uploaded file.
HTTP 202
Idempotency-Key header. A retry with the same key and body returns the original Job.
Poll the Job
result, one per block and format:
HTTP 200 (excerpt)
Download the output
Fetch eachdownload_url with your API key. In a linear workflow, the highest block_number is the final output; a branching workflow can have several output files. For complete download code in each language, see Download Workflow output.
cURL
Run on an uploaded file
A workflow whose first block is Upload Data (read_csv) reads its rows from a file. Upload the file with POST /v1/files, then pass the returned file_id as source_overrides.resource_handle_id:
cURL
Output formats
CSV is the default. To also save NDJSON, sendresult_formats when starting the run. NDJSON keeps numbers, booleans and nested objects typed, where CSV writes every value as text.
cURL
result then lists a file for each format. Select the one you need by content_type.
Errors
For error responses, see Handling Errors.Pricing
See Credit Costs for more information.Integrations built on
/workflows/run and the other original routes keep working. Legacy maps each one to its /v1 replacement.