> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hollr.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hollr.ai/_mcp/server.

# Batches

Use the Batches API when your application needs to trigger multiple calls under the same campaign in one request — optionally scheduled for later — and then track or manage that batch over its lifecycle.

A batch is created once and moves through a small set of statuses: `pending` / `scheduled` → `in_progress` → `completed`, or `paused` / `failed` along the way. Every batch action below (other than the metadata-only rename in [Update a batch](#update-a-batch)) is synced to HollrAI's calling server, so the batch record in HollrAI always reflects what's actually happening on the call queue.

#### Create a batch

Use `/v1/call/create-batch` to enqueue a batch of contacts under a campaign, either immediately or at a scheduled time.

```bash
curl -X POST https://api.hollr.ai/v1/call/create-batch \
  -H "hollr-api-key: $HOLLR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "CAMPAIGN_ID",
    "name": "Monday Morning Calls",
    "contacts": [
      {
        "name": "Jane Doe",
        "phone_number": "+15551234567"
      },
      {
        "name": "John Smith",
        "phone_number": "+15557654321",
        "other_details": {
          "appointmentDate": "2026-08-14"
        }
      }
    ],
    "run_now": false,
    "scheduled_for": "2026-08-15T09:00:00Z"
  }'
```

`campaign_id`, `name`, and `contacts` are required. Each contact requires a `name` and `phone_number`; `other_details` can carry additional contact information.

Set `run_now: true` to start the batch immediately — or omit `scheduled_for` entirely, which defaults to immediate. To schedule for later, set `scheduled_for` to an ISO 8601 timestamp **with an explicit UTC offset** (e.g. `2026-08-15T09:00:00Z`). A timestamp without a `Z` or offset is rejected rather than guessed; convert local time to UTC before sending. `scheduled_for` must also be in the future.

If the batch is created but HollrAI's call server fails to enqueue it, the batch record is kept with status `failed` rather than discarded — you can inspect it with [Get a batch](#get-a-batch) and retry with [Reschedule a batch](#reschedule-a-batch).

#### List batches

Use `/v1/call/batches` to list all batches for a campaign.

```bash
curl -X GET "https://api.hollr.ai/v1/call/batches?campaign_id=CAMPAIGN_ID" \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

`campaign_id` is required as a query parameter. Batches are returned newest first.

#### Get a batch

Use `/v1/call/batches/{batch_id}` to fetch one batch's stored details, including its contacts, status, and schedule.

```bash
curl -X GET https://api.hollr.ai/v1/call/batches/BATCH_ID \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

This returns what HollrAI has stored for the batch. For live in-progress counts, use [Get batch status](#get-batch-status).

#### Get batch status

Use `/v1/call/batches/{batch_id}/status` to get the batch's live progress from the call server — completed, failed, active, and waiting call counts.

```bash
curl -X GET https://api.hollr.ai/v1/call/batches/BATCH_ID/status \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

This call reaches out to the call server for the current state and syncs the batch's stored status in HollrAI to match, so repeated polling keeps your batch records fresh.

#### Pause a batch

Use `/v1/call/batches/{batch_id}/pause` to pause a batch that's currently `pending`, `scheduled`, or `in_progress`.

```bash
curl -X POST https://api.hollr.ai/v1/call/batches/BATCH_ID/pause \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

No request body is needed. Pausing a batch that isn't in a pausable state returns a `400`.

#### Resume a batch

Use `/v1/call/batches/{batch_id}/resume` to resume a batch that's currently `paused`.

```bash
curl -X POST https://api.hollr.ai/v1/call/batches/BATCH_ID/resume \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

No request body is needed. Resuming a batch that isn't `paused` returns a `400`.

#### Reschedule a batch

Use `/v1/call/batches/{batch_id}/reschedule` to change a batch's contacts and/or its `scheduled_for` time. This hits the call queue directly — use this (not [Update a batch](#update-a-batch)) whenever contacts or timing need to change.

```bash
curl -X POST https://api.hollr.ai/v1/call/batches/BATCH_ID/reschedule \
  -H "hollr-api-key: $HOLLR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_for": "2026-08-16T09:00:00Z"
  }'
```

Provide `contacts`, `scheduled_for`, or both — at least one is required. Omitting `contacts` keeps the batch's existing contact list; omitting `scheduled_for` keeps its existing schedule. The same UTC-offset requirement from [Create a batch](#create-a-batch) applies to `scheduled_for` here.

#### Update a batch

Use `/v1/call/batches/{batch_id}` (`PATCH`) to rename a batch or edit `scheduled_for` **without** touching contacts or the call queue. This is a metadata-only update — if you need to change contacts or push the change to the call server, use [Reschedule a batch](#reschedule-a-batch) instead.

```bash
curl -X PATCH https://api.hollr.ai/v1/call/batches/BATCH_ID \
  -H "hollr-api-key: $HOLLR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monday Morning Calls (renamed)"
  }'
```

Provide `name`, `scheduled_for`, or both — at least one is required.

#### Delete a batch

Use `/v1/call/batches/{batch_id}` (`DELETE`) to cancel a batch on the call server and remove its record from HollrAI.

```bash
curl -X DELETE https://api.hollr.ai/v1/call/batches/BATCH_ID \
  -H "hollr-api-key: $HOLLR_API_KEY"
```

If the call server fails to cancel the batch, the local record is kept (rather than silently deleted) so you can retry.

## Response

Batch endpoints that reach the call server (create, status, pause, resume, reschedule) may include a pass-through object from HollrAI's underlying call server, so the API reference intentionally exposes that portion as an open object rather than a fixed schema.

## Limits

Batch endpoints share the standard 60 requests/minute limit per API key. The concurrent-call limit does not apply to batch endpoints.

See [errors and rate limits](/errors-and-rate-limits) for the full details.

## After a batch runs

Individual calls placed by a batch can be read through the [Conversations API](/conversations), the same way calls from `make-call` are — a batch is just a way of triggering many calls under one campaign at once.