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

# Batch Calling

Queue many outbound calls in one request. A batch validates and stores every recipient, then we dial them in the background up to a concurrency limit you set.

<Warning title="Compliance" icon="triangle-exclamation">
  **Compliance**
  You are solely responsible for remaining compliant with relevant local regulations for dialing including the Telephone
  Consumer Protection Act (TCPA).

  See Cartesia's [Acceptable Use Policy](https://cartesia.ai/legal/acceptable-use.html) for more detail.
</Warning>

[Create a batch](#create-a-batch) with your recipient list, then [track its progress](#track-progress) as calls dial. Use [Retry Call Batch](#retry-a-batch) to re-dial the recipients whose calls failed. You can also list your batches and [cancel a batch](#cancel-a-batch) to stop any calls still queued.

## Create a batch

Send up to 5,000 recipients with the agent and phone number to dial from. See [Create Call Batch](/api-reference/agents/call-batches/create-call-batch) for more details.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.cartesia.ai/agents/calls/batches" \
    -H "X-API-Key: $CARTESIA_API_KEY" \
    -H "Cartesia-Version: 2026-03-01" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "March outreach",
      "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
      "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
      "target_concurrency_limit": 10,
      "recipients": [
        { "to_number": "+14155559876", "metadata": { "customer_id": "cust_123" } },
        { "to_number": "+14155550101", "metadata": { "customer_id": "cust_456" } }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "X-API-Key": "YOUR_CARTESIA_API_KEY",
      "Cartesia-Version": "2026-03-01",
      "Content-Type": "application/json",
  }

  payload = {
      "name": "March outreach",
      "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
      "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
      "target_concurrency_limit": 10,
      "recipients": [
          {"to_number": "+14155559876", "metadata": {"customer_id": "cust_123"}},
          {"to_number": "+14155550101", "metadata": {"customer_id": "cust_456"}},
      ],
  }

  response = requests.post(
      "https://api.cartesia.ai/agents/calls/batches", headers=headers, json=payload
  )
  response.raise_for_status()
  batch = response.json()
  print(batch["id"])  # save to track or cancel the batch
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "acb_PDWFN995PzAudChwFDqVZ2",
  "name": "March outreach",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "region": "US",
  "target_concurrency_limit": 10,
  "status": "pending",
  "total_calls_scheduled": 2,
  "total_calls_dispatched": 0,
  "total_calls_finished": 0,
  "retry_count": 0,
  "created_at": "2026-03-01T12:00:00Z",
  "last_updated_at": "2026-03-01T12:00:00Z"
}
```

The API returns **201** with the batch and its derived progress counters. Save the `id` to track or cancel the batch.

`target_concurrency_limit` caps how many of the batch's calls dial at once. If unspecified, it defaults to half of your organization's agent-call concurrency limit, leaving headroom for other calls. It must not exceed that limit, or the request is rejected. Batch calling counts only against your [agent-call concurrency limit](/line/infrastructure/scaling), not TTS or STT limits.

Each batch reserves its `target_concurrency_limit` against your organization's shared agent-call concurrency limit. If there isn't enough capacity when the batch is ready to run, it stays `pending` and starts dialing automatically once your running batches free up capacity, oldest batch first.

To run the batch later, set `scheduled_at` to an RFC3339 time with a timezone offset, for example `2026-06-15T16:00:00Z`

## Track progress

Fetch a batch with [Get Call Batch](/api-reference/agents/call-batches/get-call-batch) to see its status and per-recipient detail.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2" \
    -H "X-API-Key: $CARTESIA_API_KEY" \
    -H "Cartesia-Version: 2026-03-01"
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "X-API-Key": "YOUR_CARTESIA_API_KEY",
      "Cartesia-Version": "2026-03-01",
  }

  response = requests.get(
      "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2",
      headers=headers,
  )
  response.raise_for_status()
  batch = response.json()

  print(batch["status"])
  for recipient in batch["recipients"]:
      print(recipient["to_number"], recipient["status"])
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "acb_PDWFN995PzAudChwFDqVZ2",
  "name": "March outreach",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "region": "US",
  "target_concurrency_limit": 10,
  "status": "in_progress",
  "total_calls_scheduled": 2,
  "total_calls_dispatched": 1,
  "total_calls_finished": 1,
  "retry_count": 0,
  "created_at": "2026-03-01T12:00:00Z",
  "last_updated_at": "2026-03-01T12:05:00Z",
  "recipients": [
    {
      "id": "abcr_295cx2ZMPitmqQtBtWUxSR",
      "to_number": "+14155559876",
      "status": "completed",
      "agent_call_id": "ac_2u7rspBaHJ7bQ7TiR3mK2n",
      "end_reason": "agent_hangup",
      "metadata": { "customer_id": "cust_123" },
      "created_at": "2026-03-01T12:00:00Z"
    },
    {
      "id": "abcr_TD5XMc9uNw6mJfhFbcvQTm",
      "to_number": "+14155550101",
      "status": "queued",
      "metadata": { "customer_id": "cust_456" },
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}
```

The batch [`status`](/api-reference/agents/call-batches/get-call-batch#response-status) tracks dispatch progress, and each recipient's [`status`](/api-reference/agents/call-batches/get-call-batch#response-recipients-items-status) tracks its own call.

Use each recipient's `agent_call_id` to fetch per-call information via [Get Call](/api-reference/agents/calls/get-call). A recipient that fails before any call is placed has no `agent_call_id`; read its `error_message` for more information.

To list every batch in your workspace, optionally filtered by agent, use [List Call Batches](/api-reference/agents/call-batches/list-call-batches).

## Retry a batch

Retry a batch with [Retry Call Batch](/api-reference/agents/call-batches/retry-call-batch) to re-dial the recipients whose latest attempt failed or went unanswered. It re-queues only those recipients so the dispatcher dials them again; recipients that successfully completed their call are left untouched. A cancelled batch cannot be retried.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/retry" \
    -H "X-API-Key: $CARTESIA_API_KEY" \
    -H "Cartesia-Version: 2026-03-01"
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "X-API-Key": "YOUR_CARTESIA_API_KEY",
      "Cartesia-Version": "2026-03-01",
  }

  response = requests.post(
      "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/retry",
      headers=headers,
  )
  response.raise_for_status()
  batch = response.json()
  print(batch["retry_count"])  # incremented when failed recipients were re-queued
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "acb_PDWFN995PzAudChwFDqVZ2",
  "name": "March outreach",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "region": "US",
  "target_concurrency_limit": 10,
  "status": "in_progress",
  "total_calls_scheduled": 2,
  "total_calls_dispatched": 1,
  "total_calls_finished": 1,
  "retry_count": 1,
  "created_at": "2026-03-01T12:00:00Z",
  "last_updated_at": "2026-03-01T12:07:00Z"
}
```

## Cancel a batch

Cancel a batch with [Cancel Call Batch](/api-reference/agents/call-batches/cancel-call-batch) to stop dialing its queued calls. Calls already in flight finish normally.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/cancel" \
    -H "X-API-Key: $CARTESIA_API_KEY" \
    -H "Cartesia-Version: 2026-03-01"
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "X-API-Key": "YOUR_CARTESIA_API_KEY",
      "Cartesia-Version": "2026-03-01",
  }

  response = requests.post(
      "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2/cancel",
      headers=headers,
  )
  response.raise_for_status()
  batch = response.json()
  print(batch["status"])  # "cancelled"
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "acb_PDWFN995PzAudChwFDqVZ2",
  "name": "March outreach",
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "region": "US",
  "target_concurrency_limit": 10,
  "status": "cancelled",
  "total_calls_scheduled": 2,
  "total_calls_dispatched": 1,
  "total_calls_finished": 1,
  "retry_count": 0,
  "created_at": "2026-03-01T12:00:00Z",
  "last_updated_at": "2026-03-01T12:06:00Z"
}
```