Skip to main content
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.
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 for more detail.
Create a batch with your recipient list, then track its progress as calls dial. Use Retry Call Batch to re-dial the recipients whose calls failed. You can also list your batches and 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 for more details. 
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" } }
    ]
  }'
Response
{
  "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, 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 to see its status and per-recipient detail. 
curl "https://api.cartesia.ai/agents/calls/batches/acb_PDWFN995PzAudChwFDqVZ2" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01"
Response
{
  "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 tracks dispatch progress, and each recipient’s status tracks its own call. Use each recipient’s agent_call_id to fetch per-call information via 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.

​
Retry a batch

Retry a batch with 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. 
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"
Response
{
  "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 to stop dialing its queued calls. Calls already in flight finish normally. 
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"
Response
{
  "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"
}