> ## 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 research 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 /v1/workflows/{workflow_id}/runs"] --> Poll["GET /v1/jobs/{job_id}"] --> Download["GET download_url"]
```

`POST /v1/workflows/{workflow_id}/runs` starts the run and returns a Job. What you send depends on the workflow's first block:

* Incoming Webhooks: pass the rows in `input`, a list of objects, one per row.
* Upload Data (`read_csv`): [upload the file](https://docs.sixtyfour.ai/api-reference/workflows/workflows-overview.md#run-on-an-uploaded-file) and pass its `file_id` as `source_overrides.resource_handle_id`.
* Any other first block: send an empty body, `{}`.

The run is asynchronous. Poll `GET /v1/jobs/{job_id}` until `status` is `succeeded`, `failed` or `canceled`, waiting `next_poll_after` seconds between polls. A finished Job lists one output file per block in `result`. The file with the highest `block_number` is the final output. Fetch its `download_url` with your `x-api-key` header.

```bash cURL theme={null}
set -euo pipefail
API=https://api.sixtyfour.ai

# Start the run
JOB=$(curl --fail-with-body -sS "$API/v1/workflows/WORKFLOW_ID/runs" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"name": "Sarah Chen", "company": "Pacific View Studios"},
      {"name": "James Park", "company": "Northgate Labs"}
    ]
  }')

# Poll until the Job finishes
while [ "$(echo "$JOB" | jq -r .status)" != "succeeded" ]; do
  case "$(echo "$JOB" | jq -r .status)" in failed|canceled) echo "$JOB"; exit 1;; esac
  sleep "$(echo "$JOB" | jq -r '.next_poll_after // 5')"
  JOB=$(curl --fail-with-body -sS "$API/v1/jobs/$(echo "$JOB" | jq -r .job_id)" -H "x-api-key: YOUR_API_KEY")
done

# Download the final output
curl --fail-with-body -sS "$(echo "$JOB" | jq -r '.result | max_by(.block_number) | .download_url')" \
  -H "x-api-key: YOUR_API_KEY" -o results.csv
```

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

API = "https://api.sixtyfour.ai"
headers = {"x-api-key": "YOUR_API_KEY"}

response = requests.post(
    f"{API}/v1/workflows/WORKFLOW_ID/runs",
    headers=headers,
    json={"input": [
        {"name": "Sarah Chen", "company": "Pacific View Studios"},
        {"name": "James Park", "company": "Northgate Labs"},
    ]},
)
response.raise_for_status()
job = response.json()

while job["status"] not in ("succeeded", "failed", "canceled"):
    time.sleep(job.get("next_poll_after") or 5)
    response = requests.get(f"{API}/v1/jobs/{job['job_id']}", headers=headers)
    response.raise_for_status()
    job = response.json()
if job["status"] != "succeeded":
    raise RuntimeError(f"Run ended as {job['status']}")

final = max(job["result"], key=lambda file: file["block_number"])
download = requests.get(final["download_url"], headers=headers)
download.raise_for_status()
with open("results.csv", "wb") as output:
    output.write(download.content)
```

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

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

const started = await fetch(API + "/v1/workflows/WORKFLOW_ID/runs", {
  method: "POST",
  headers,
  body: JSON.stringify({
    input: [
      { name: "Sarah Chen", company: "Pacific View Studios" },
      { name: "James Park", company: "Northgate Labs" },
    ],
  }),
});
if (!started.ok) throw new Error(await started.text());
let job = await started.json();

while (!["succeeded", "failed", "canceled"].includes(job.status)) {
  await new Promise((resolve) => setTimeout(resolve, (job.next_poll_after ?? 5) * 1000));
  const poll = await fetch(API + "/v1/jobs/" + job.job_id, { headers });
  if (!poll.ok) throw new Error(await poll.text());
  job = await poll.json();
}
if (job.status !== "succeeded") throw new Error("Run ended as " + job.status);

const final = job.result.reduce((a, b) => (b.block_number > a.block_number ? b : a));
const download = await fetch(final.download_url, { headers });
if (!download.ok) throw new Error(await download.text());
await writeFile("results.csv", Buffer.from(await download.arrayBuffer()));
```

For the Job's fields and a full response, see [Check a run](https://docs.sixtyfour.ai/api-reference/workflows/workflows-execution.md#check-a-run).

> [!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` query string for the file exactly as stored, or send `"result_formats": ["csv", "ndjson"]` when code reads the results. See [Spreadsheet-safe CSV](https://docs.sixtyfour.ai/api-reference/workflows/workflows-execution.md#spreadsheet-safe-csv).

Retrying the request with the same `Idempotency-Key` header and body returns the existing Job instead of starting a new run. [Workflow Execution](https://docs.sixtyfour.ai/api-reference/workflows/workflows-execution.md) covers cancellation, failed rows, output formats and every response field. 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). The original `/workflows/run` routes keep working and are documented under [Legacy](https://docs.sixtyfour.ai/api-reference/legacy/workflows-execution.md).

## Tips

* Filter before research. 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 Intelligence 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.