Core conceptsCalls

Batches

Trigger and manage batches of AI calls
View as Markdown

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) is synced to HollrAI’s calling server, so the batch record in HollrAI always reflects what’s actually happening on the call queue.

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

$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 and retry with Reschedule a batch.

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 for the full details.

After a batch runs

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