Use case
Execute batch enrichment pipelines, monitor progress in real time, and retrieve results. Use these endpoints to run workflows with input data, poll for completion, cancel long-running runs, and download enriched output files.API Reference
See the full request/response schema and parameters in the API Reference.
Pricing
See Credits & Pricing Guide for credit costs.Errors
For error responses (400, 403, 404, 409, etc.), see Handling Errors.Run workflow
Execute a workflow and receive a job ID for tracking.workflow_id as a query parameter. The optional request body accepts specs_override (to override the first block’s specs for dynamic inputs) and webhook_payload (input data for workflows starting with a webhook block).
Request Body (Optional)
Example Request
read_csv workflows, use the handle_id returned by /storage/csv/upload:
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.status (running, completed, cancelled, or active), workflow_id, and limit (1–500, default 100). Results are sorted by most recent first (queued_at descending). For failed runs, error_message and status_reason may be populated.
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
Polling recommendations
- Poll every 5–10 seconds for running workflows
- Stop polling when
overall_statusiscompleted,failed, orcancelled - Use
overall_progress_percentagefor progress bars
Cancel run
Stop an in-progress workflow execution.job_id (from the Run Workflow response) as a query parameter. The request body is optional — send an empty object {} or omit.
If the run has already completed, failed, or been cancelled, the API returns the current status without changes. Partial results may be available.
Download results
Get signed download URLs for workflow results.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
Failedin the columns the failing step would have filled - is still sent to an outgoing webhook step
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.