Automate and schedule calls using Batches

What is Batch Calling?

Batch calling lets you automate outbound calls to hundreds or thousands of contacts by uploading a CSV file with phone numbers and custom data. Ideal for lead qualification, customer outreach, appointment reminders, and other high-volume calling campaigns. There are two ways to run batches, and both do the same thing:

From the dashboard

No code. Upload a CSV under Deploy → Batches, then run now or schedule.

From the API

Create, schedule, and track batches programmatically with the Batch API.

CSV File Format

Your CSV file must follow these rules:

Use E.164 Phone Format

All phone numbers must include the country prefix in E.164 format (e.g., +11231237890).

Use contact_number Header

The phone number column must use contact_number as the header.

Add Custom Variables

Include any additional variables (name, address, etc.) as separate columns. These are passed to the agent as context.

example_batch_file.csv

contact_number,first_name,last_name
+11231237890,Bruce,Wayne
+91012345678,Bruce,Lee
+00021000000,Satoshi,Nakamoto
+44999999007,James,Bond

In Excel, typing + at the beginning of a cell is interpreted as a formula. Add an apostrophe (') before the plus sign to retain it.

Download an example CSV file

Only the contact_number column is validated for correctness. Other columns (custom variables like first_name, address, etc.) are passed through as-is without any validation. The exception is agent_language on a multilingual agent, described below.

Multilingual agents: add an agent_language column to start each row’s call in a different configured language (for example hi or ta). A blank cell uses the agent’s default language, and a row naming a language the agent doesn’t have is marked error at upload while the rest of the batch runs. See Start a call in a chosen language.

How to run batches from the dashboard?

You can upload batches, schedule them, and configure auto-retry directly from the Bolna platform — no code and no API key needed.

Open Deploy → Batches

In the left sidebar, expand Deploy and click Batches. Pick an agent from the selector at the top to list its batches, along with Batch ID, File name, Uploaded contacts, Execution Status, Batch Status, Workflow, Created At and the Run Now, Stop, Download, Delete and Call Log actions.Click Upload Batch to get started.

Agent Batches list — Agent Batches overview showing batch status, execution details, and available actions

Upload Your CSV

Drag and drop your CSV file or click to browse. After uploading, you’ll see how many rows were parsed and how many contacts have valid phone numbers.

Upload Batch dialog with CSV upload, phone number selection, scheduling, and webhook options

In this dialog you can:

Select a phone number to make calls from (Bolna managed or your own)
Choose to Run Now or Schedule the batch for a future date and time
Enable auto-retry for unconnected calls
Set a webhook URL to receive real-time call status updates

Schedule or Run Now

Select Run Now to start calls immediately, or click Schedule to pick a future date and time. Use the quick-select buttons to schedule 15 minutes, 30 minutes, or 2 hours from now. Scheduled times must be less than 30 days ahead of the current time.

Schedule batch options — Scheduling options with Run Now, Schedule, and quick-select time buttons

Configure Auto-Retry (Optional)

Enable Auto-retry unconnected calls to automatically re-attempt calls that didn’t connect. You can configure:

Retry on: Select which call outcomes trigger a retry (No Answer, Busy, Failed, Error, Retry on voicemail)
Maximum retry attempts: Set up to 3 retry attempts per contact
Retry intervals: Define increasing delays between attempts (e.g., 30 min, 60 min, 120 min)
Prioritize retries: Place retries ahead of pending first attempts

Auto-retry configuration — Auto-retry settings with retry conditions, max attempts, and configurable intervals

Click Confirm to upload. Your batch appears in the batches list with its scheduled time and status.

Webhook Notifications

You can provide a Webhook URL in the upload dialog to receive real-time updates as each call in the batch completes. Bolna sends a POST request to your webhook endpoint with the call’s execution data, including the call status, transcript, extracted data, and cost breakdown. This is useful for syncing call results to your CRM, triggering follow-up workflows, or logging outcomes in real time without polling the API.

If you don’t set a webhook, you can still retrieve all results later using the List Batch Executions API.

How to run batches using the API?

Create a Batch

Upload your CSV file using the Create Batch API:

curl --location 'https://api.bolna.ai/batches' \
--header 'Authorization: Bearer <api_key>' \
--form 'agent_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"' \
--form 'file=@"/my-first-batch.csv"' \
--form 'from_phone_numbers="+919876543210"' \
--form 'from_phone_numbers="+919876543211"'

{
    "batch_id": "abcdefghijklmnopqrstuvwxyz012345",
    "state": "created"
}

Schedule the Batch

Use the batch_id to schedule via the Schedule Batch API. The date and time must be in ISO 8601 format with timezone:

curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/schedule' \
--header 'Authorization: Bearer <api_key>' \
--form 'scheduled_at="2024-03-20T04:05:00+00:00"'

{
    "message": "success",
    "state": "scheduled at 2024-03-20T04:10:00+00:00"
}

Check Batch Status

Monitor progress using the Get Batch API:

curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345' \
--header 'Authorization: Bearer <api_key>'

{
    "batch_id": "abcdefghijklmnopqrstuvwxyz012345",
    "humanized_created_at": "19 minutes ago",
    "created_at": "2024-03-13T14:12:50.596315",
    "updated_at": "2024-03-13T14:19:13.115411",
    "status": "scheduled",
    "scheduled_at": "2024-03-20T04:10:00+05:30"
}

Retrieve Executions

After the batch completes, fetch all execution results using the List Batch Executions API:

curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/executions' \
--header 'Authorization: Bearer <api_key>'

[
  {
    "id": 7432382142914,
    "conversation_duration": 123,
    "total_cost": 123,
    "transcript": "<string>",
    "createdAt": "2024-01-23T01:14:37Z",
    "updatedAt": "2024-01-29T18:31:22Z",
    "usage_breakdown": {
      "synthesizerCharacters": 123,
      "synthesizerModel": "polly",
      "transcriberDuration": 123,
      "transcriberModel": "deepgram",
      "llmTokens": 123,
      "llmModel": {
        "gpt-3.5-turbo-16k": {
          "output": 28,
          "input": 1826
        }
      }
    }
  }
]

Complete Example

Python script using all Batch APIs together

batch_script.py

import asyncio
import os
from dotenv import load_dotenv
import aiohttp

# Load environment variables from .env file
load_dotenv()

# Load from .env
host = "https://api.bolna.ai"
api_key = os.getenv("api_key", None)
agent_id = 'ee153a6c-19f8-3a61-989a-9146a31c7834'  # Agent to create batch for
file_path = '/path/of/csv/file'
schedule_time = '2024-06-01T04:10:00+05:30'
from_phone_numbers = ['+919876543210', '+919876543211']


async def schedule_batch(api_key, batch_id, scheduled_at):
    print("Scheduling batch for batch_id: {}".format(batch_id))
    url = f"{host}/batches/{batch_id}/schedule"
    headers = {'Authorization': f'Bearer {api_key}'}
    data = {'scheduled_at': scheduled_at}

    try:
        async with aiohttp.ClientSession() as session:
            async with session.post(url, headers=headers, data=data) as response:
                response_data = await response.json()
                if response.status == 200:
                    return response_data
                else:
                    raise Exception(f"Error scheduling batch: {response_data}")
    except aiohttp.ClientError as e:
        print(f"HTTP Client Error: {str(e)}")
    except Exception as e:
        print(f"Unexpected error: {str(e)}")


async def get_batch_status(api_key, batch_id):
    print("Getting batch status for batch_id: {}".format(batch_id))
    url = f"{host}/batches/{batch_id}"
    headers = {'Authorization': f'Bearer {api_key}'}

    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, headers=headers) as response:
                response_data = await response.json()
                if response.status == 200:
                    return response_data
                else:
                    raise Exception(f"Error getting batch status: {response_data}")
    except aiohttp.ClientError as e:
        print(f"HTTP Client Error: {str(e)}")
    except Exception as e:
        print(f"Unexpected error: {str(e)}")


async def get_batch_executions(api_key, batch_id):
    print("Getting batch executions for batch_id: {}".format(batch_id))
    url = f"{host}/batches/{batch_id}/executions"
    headers = {'Authorization': f'Bearer {api_key}'}

    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url, headers=headers) as response:
                response_data = await response.json()
                if response.status == 200:
                    return response_data
                else:
                    raise Exception(f"Error getting batch executions: {response_data}")
    except aiohttp.ClientError as e:
        print(f"HTTP Client Error: {str(e)}")
    except Exception as e:
        print(f"Unexpected error: {str(e)}")


async def create_batch():
    url = f"{host}/batches"
    headers = {'Authorization': f'Bearer {api_key}'}

    with open(file_path, 'rb') as f:
        form_data = aiohttp.FormData()
        form_data.add_field('agent_id', agent_id)
        form_data.add_field('file', f, filename=os.path.basename(file_path))

        # Add multiple from_phone_numbers
        for phone in from_phone_numbers:
            form_data.add_field('from_phone_numbers', phone)

        async with aiohttp.ClientSession() as session:
            async with session.post(url, headers=headers, data=form_data) as response:
                response_data = await response.json()
                if response_data.get('state') == 'created':
                    batch_id = response_data.get('batch_id')
                    res = await schedule_batch(api_key, batch_id, scheduled_at=schedule_time)
                    if res.get('state') == 'scheduled':
                        check = True
                        while check:
                            # Check status every 1 minute
                            await asyncio.sleep(60)
                            res = await get_batch_status(api_key, batch_id)
                            if res.get('status') == 'completed':
                                check = False
                                break
                    if not check:
                        res = await get_batch_executions(api_key, batch_id)
                        print(res)
                        return res


if __name__ == "__main__":
    asyncio.run(create_batch())

Next Steps

Concurrency Limits

Understand outbound calling concurrency limits

Buy Phone Numbers

Set up dedicated phone numbers for campaigns

Context Variables

Personalize each call with dynamic data

Auto-Retry

Automatically retry failed calls

Quickstarts

Phone Numbers & Calling Setup

Outbound Calling

Inbound Calling

Native Telephony Integrations

Managing Live Calls

Prompting & Personalization

Tools & Function Calling

Post-Call & Analytics

No-Code & Automation

SIP Trunking Guide

Automate and schedule calls using Batches

What is Batch Calling?

From the dashboard

From the API

CSV File Format

How to run batches from the dashboard?

Webhook Notifications

How to run batches using the API?

Complete Example

Next Steps

Concurrency Limits

Buy Phone Numbers

Context Variables

Auto-Retry

​What is Batch Calling?

From the dashboard

From the API

​CSV File Format

​How to run batches from the dashboard?

​Webhook Notifications

​How to run batches using the API?

​Complete Example

​Next Steps

Concurrency Limits

Buy Phone Numbers

Context Variables

Auto-Retry

What is Batch Calling?

CSV File Format

How to run batches from the dashboard?

Webhook Notifications

How to run batches using the API?

Complete Example

Next Steps