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. You can also list your batches and cancel a batch to stop any calls still queued.

​
Create a batch

Send up to 1,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,
  "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. 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,
  "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.

​
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,
  "created_at": "2026-03-01T12:00:00Z",
  "last_updated_at": "2026-03-01T12:06:00Z"
}