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

# Batch runs

> Run routines across many records.

Batch runs let you apply the same routine to many records.

Both functions and Workflows can be run programmatically in batches. The difference is how the routine is built:

* Functions are built and managed in the Clay UI, then run or batch-run programmatically.
* Workflows are in Alpha and can be built, edited, run, inspected, and batch-run from the plugin or CLI.

## Function batch runs

Use function batch runs when you have a Clay-managed function or custom function and want to apply it to a list of inputs.

CLI function batch runs use JSONL input:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay routines runs start function:t_abc123 --bulk rows.jsonl
```

Each JSONL line is one item:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "id": "row-1", "inputs": { "domain": "clay.com" } }
```

The CLI wraps the same Public API flow:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST "https://api.clay.com/public/v0/routines/function:t_abc123/run-batch/upload-url" \
  --header "clay-api-key: $CLAY_API_KEY"
```

Upload the JSONL file to the returned `upload_url`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT "$UPLOAD_URL" \
  --header "Content-Type: application/x-ndjson" \
  --data-binary @rows.jsonl
```

Start the batch run with the returned `file_id`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST "https://api.clay.com/public/v0/routines/function:t_abc123/run-batch/start" \
  --header "clay-api-key: $CLAY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "file_id": "file_abc123" }'
```

Then fetch progress and the result URL:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET "https://api.clay.com/public/v0/routines/run-batch/run_xyz789/results" \
  --header "clay-api-key: $CLAY_API_KEY"
```

## Workflow batch runs

Use Workflow batch runs when you want the Workflow itself to be built and managed from the plugin or CLI.

Workflows are in Alpha. They are useful when you need agent-first building, run inspection, snapshots, code inside the flow, or runs that avoid the 50,000 row limit.

<Card title="Workflows (Alpha)" href="/routines/workflows-alpha">
  Learn when to use Workflows.
</Card>