Skip to main content

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.
Pass 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

For read_csv workflows, use the handle_id returned by /storage/csv/upload:
Use the job_id returned in the response to track workflow execution. Check the workflow editor’s “Workflow API Reference” for specific specs_override options.
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.
Optional query parameters: 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_status is completed, failed, or cancelled
  • 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 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.
Returns one entry per result file. Each block may produce separate files; results are typically in CSV format.
Signed URLs expire after 15 minutes (900 seconds). Download files immediately or request new links.

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
  • 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