create-batch

Create Bolna Batch Campaigns

Endpoints

• Create batch: POST https://api.bolna.ai/batches
• Schedule batch: POST https://api.bolna.ai/batches/{batch_id}/schedule
• Stop batch: POST https://api.bolna.ai/batches/{batch_id}/stop
• Get batch: GET https://api.bolna.ai/batches/{batch_id}
• List batches for agent: GET https://api.bolna.ai/batches/{agent_id}/all
• List batch executions: GET https://api.bolna.ai/batches/{batch_id}/executions
• Delete batch: DELETE https://api.bolna.ai/batches/{batch_id}

CSV format

The CSV must include recipient phone numbers and any variables referenced by the agent prompt.

contact_number,customer_name,plan
+919876543210,Amitesh,Pro
+918765432109,Riya,Starter

If the agent prompt says {customer_name} or {plan}, the CSV needs matching columns. Use contact_number for the recipient number header. Bolna validates that column and passes the other columns through as custom variables.

Create batch

Use multipart form upload.

curl --location https://api.bolna.ai/batches \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --form 'agent_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"' \
  --form 'file=@"/path/to/recipients.csv"' \
  --form 'from_phone_numbers="+919876543210"' \
  --form 'from_phone_numbers="+919876543211"'

Optional retry config is a JSON string:

--form 'retry_config={"enabled":true,"max_retries":2,"retry_intervals_minutes":[15,30]}'

Expected response:

{
  "batch_id": "3c90c3cc0d444b5088888dd25736052a",
  "state": "created"
}

Schedule batch

curl --location "https://api.bolna.ai/batches/$BATCH_ID/schedule" \
  --header "Authorization: Bearer $BOLNA_API_KEY" \
  --form 'scheduled_at="2026-05-19T18:30:00+05:30"' \
  --form 'bypass_call_guardrails=false'

Always include timezone in scheduled_at.

Monitor

curl --request GET \
  --url "https://api.bolna.ai/batches/$BATCH_ID" \
  --header "Authorization: Bearer $BOLNA_API_KEY"

Use execution counts and statuses to track completion. For per-call transcript, cost, recording, and extracted data, list batch executions.

Stop and delete

Stopping a batch halts its remaining queued work. Deleting a batch removes it from batch management. Confirm the user's intent before either operation.

Asset

Use assets/sample_recipients.csv as a starter template.

Scripts

# Create a batch from a CSV
python3 create-batch/scripts/create_batch.py \
  --agent-id "$AGENT_ID" \
  --file recipients.csv \
  --from-numbers "+919876543210,+919876543211"

# Poll a batch's progress until terminal
python3 create-batch/scripts/monitor_batch.py --batch-id "$BATCH_ID"

Retry vs concurrency

Per-call retry_config shares the same concurrency tier as the batch itself. If a batch is at its concurrency cap and retries kick in, retries queue behind the in-flight calls — effectively slowing the campaign. For high-volume campaigns:

• Lower max_retries to 1 (or 0).
• Or run the campaign under-cap so retries don't block fresh dials.

See also

• make-call — single-call interface; shares the retry_config shape.
• get-executions — GET /batches/{batch_id}/executions paginates per-call results.
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/call-statuses.md — terminal-status filter for batch summary.
• https://raw.githubusercontent.com/bolna-ai/skills/main/references/india-compliance.md — DLT prerequisites for Indian recipient batches.