> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sixtyfour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Batches

> Process every record in a file or list through a workflow.

Build the workflow once in the [Workflow Editor](https://docs.sixtyfour.ai/guides/building-workflows.md) or [as JSON](https://docs.sixtyfour.ai/guides/programmatic-workflows.md), then feed it rows.

| Input | How | Best for |
| - | - | - |
| A file you have | Start the workflow with an Upload Data block and attach a CSV, JSON, or NDJSON file in the editor | One-off lists |
| Rows from your systems | Start the workflow with an Incoming Webhooks block and send rows in the API request | Recurring jobs and integrations |
| A search | Start the workflow with a Find Data block such as Search | Building a new list |

To enrich a list with People or Company Intelligence and nothing else, [Bulk Intelligence](https://docs.sixtyfour.ai/api-reference/endpoint/bulk-intelligence.md) needs no workflow.

## Run a batch in the editor

1. Open the workflow and click Run. The run dialog shows the estimated cost.
2. Click Runs in the editor header to follow progress block by block.
3. Download the results from the run, or deliver them with a Send Results block such as Append to Notebook or Outgoing Webhooks.

## Send rows in the request

Runs started through the API follow three steps:

```mermaid theme={null}
flowchart LR
  Run["POST /workflows/run"] --> Poll["GET .../live_status"] --> Download["GET .../results/download-links"]
```

`POST /workflows/run?workflow_id=WORKFLOW_ID` starts the run. For a workflow whose source block is Incoming Webhooks, pass the rows in `webhook_payload`: a list of objects, one per row, or a single object for one row. For an Upload Data (`read_csv`) source, [upload the input file](https://docs.sixtyfour.ai/api-reference/workflows/workflows-overview.md#uploading-an-input-file) and pass its `handle_id` as `specs_override.resource_handle_id` in the request body. Workflows that start with other source blocks run with no body.

The run is asynchronous. Poll `live_status` every 10 seconds or slower while `overall_status` is `queued`, `running`, or `finalizing`, then request download links. The list has one file per block; the final results are the file named `{job_id}.csv`. Each `download_url` expires after 15 minutes and needs your `x-api-key` header.

```bash cURL theme={null}
# Start the run
curl -X POST "https://api.sixtyfour.ai/workflows/run?workflow_id=WORKFLOW_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_payload": [
      {"name": "Sarah Chen", "company": "Pacific View Studios"},
      {"name": "James Park", "company": "Northgate Labs"}
    ]
  }'

# Poll with the job_id from the response
curl "https://api.sixtyfour.ai/workflows/runs/JOB_ID/live_status" \
  -H "x-api-key: YOUR_API_KEY"

# Get download links once overall_status is completed
curl "https://api.sixtyfour.ai/workflows/runs/JOB_ID/results/download-links" \
  -H "x-api-key: YOUR_API_KEY"
```

```python Python theme={null}
import time, requests

BASE = "https://api.sixtyfour.ai"
HEADERS = {"x-api-key": "YOUR_API_KEY"}

run = requests.post(
    f"{BASE}/workflows/run",
    params={"workflow_id": "WORKFLOW_ID"},
    headers=HEADERS,
    json={"webhook_payload": [
        {"name": "Sarah Chen", "company": "Pacific View Studios"},
        {"name": "James Park", "company": "Northgate Labs"},
    ]},
)
run.raise_for_status()
job_id = run.json()["job_id"]

IN_PROGRESS = {"queued", "running", "finalizing"}
while True:
    resp = requests.get(f"{BASE}/workflows/runs/{job_id}/live_status", headers=HEADERS)
    if resp.status_code in (429, 503):
        time.sleep(int(resp.headers.get("Retry-After", 10)))
        continue
    resp.raise_for_status()
    status = resp.json()
    if status["overall_status"] not in IN_PROGRESS:
        break
    time.sleep(10)

if status["overall_status"] != "completed":
    raise RuntimeError(f"Run ended as {status['overall_status']}")

links = requests.get(f"{BASE}/workflows/runs/{job_id}/results/download-links", headers=HEADERS).json()
final = next(item for item in links if item["filename"] == f"{job_id}.csv")
csv_file = requests.get(final["download_url"], headers=HEADERS)
csv_file.raise_for_status()
with open("results.csv", "wb") as f:
    f.write(csv_file.content)
```

```javascript JavaScript theme={null}
import fs from "node:fs/promises";

const BASE = "https://api.sixtyfour.ai";
const headers = { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" };

const run = await fetch(`${BASE}/workflows/run?workflow_id=WORKFLOW_ID`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    webhook_payload: [
      { name: "Sarah Chen", company: "Pacific View Studios" },
      { name: "James Park", company: "Northgate Labs" },
    ],
  }),
});
const { job_id } = await run.json();

const IN_PROGRESS = ["queued", "running", "finalizing"];
let status;
while (true) {
  const resp = await fetch(`${BASE}/workflows/runs/${job_id}/live_status`, { headers });
  if (resp.status === 429 || resp.status === 503) {
    const retryAfter = Number(resp.headers.get("Retry-After") ?? 10);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    continue;
  }
  if (!resp.ok) throw new Error(`Live status failed: ${resp.status}`);
  status = await resp.json();
  if (!IN_PROGRESS.includes(status.overall_status)) break;
  await new Promise((r) => setTimeout(r, 10000));
}

if (status.overall_status !== "completed") throw new Error(`Run ended as ${status.overall_status}`);

const links = await (await fetch(`${BASE}/workflows/runs/${job_id}/results/download-links`, { headers })).json();
const final = links.find((item) => item.filename === `${job_id}.csv`);
const file = await fetch(final.download_url, { headers });
if (!file.ok) throw new Error(`Download failed: ${file.status}`);
await fs.writeFile("results.csv", Buffer.from(await file.arrayBuffer()));
```

```json Run response theme={null}
{
  "status": "RUNNING",
  "workflow_id": "0b7a3c2e-5d4f-4e8a-9c61-2f3e4d5a6b7c",
  "job_id": "5e2d8f1a-3c4b-4a6d-8e9f-1a2b3c4d5e6f"
}
```

```json Live status (abridged) theme={null}
{
  "run_id": "5e2d8f1a-3c4b-4a6d-8e9f-1a2b3c4d5e6f",
  "workflow_id": "0b7a3c2e-5d4f-4e8a-9c61-2f3e4d5a6b7c",
  "overall_status": "running",
  "current_block": "lead_enrichment",
  "total_blocks": 3,
  "completed_blocks": 1,
  "overall_progress_percentage": 48.0,
  "last_updated": "2026-01-15T10:31:12Z",
  "blocks": []
}
```

```json Download links (abridged) theme={null}
[
  {
    "filename": "5e2d8f1a-3c4b-4a6d-8e9f-1a2b3c4d5e6f_1.csv",
    "row_count": 2,
    "block_number": 1,
    "content_type": "text/csv",
    "download_url": "https://api.sixtyfour.ai/storage/download/...",
    "download_expires_in_seconds": 900
  },
  {
    "filename": "5e2d8f1a-3c4b-4a6d-8e9f-1a2b3c4d5e6f.csv",
    "row_count": 2,
    "block_number": 3,
    "content_type": "text/csv",
    "download_url": "https://api.sixtyfour.ai/storage/download/...",
    "download_expires_in_seconds": 900
  }
]
```

> [!NOTE]
>
> CSV downloads are spreadsheet-safe by default: formula-like cells, such as ones that start with `=`, `+`, or `@`, get a leading `'`, so `+14155550123` becomes `'+14155550123`. Add `?spreadsheet_safe=false` to the `download_url` for the file exactly as stored, or run with `result_formats=ndjson` when code reads the results. See [Spreadsheet-safe CSV](https://docs.sixtyfour.ai/api-reference/workflows/workflows-execution.md#spreadsheet-safe-csv).

Retrying `POST /workflows/run` with the same `Idempotency-Key` header returns the existing run instead of starting a new one. Cancellation, failed-row details, JSON and NDJSON result formats, and every response field are documented in [Workflow Execution](https://docs.sixtyfour.ai/api-reference/workflows/workflows-execution.md). For credit costs, see [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md). For error responses, see [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md).

## Tips

* Filter before enrichment. Fewer rows means faster runs and fewer credits.
* Use Deduplicate with Notebook on recurring batches so each run saves only new rows.
* Define only the return fields you need in enrichment blocks.
* Add an Outgoing Webhooks block to receive results when the run completes instead of polling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.