Outbound calling - Cartesia Docs

Place outbound calls with one API request. Provide the agent, the number to call from, and one or more destination numbers in E.164 format, such as +14155559876. from_number_id can be any phone number on your account. It does not need to be assigned to an agent, and any agent can call from it.

This endpoint dials every number immediately, so destinations beyond your agent-call concurrency limit are rejected rather than queued. For larger lists, use batch calling, which queues up to 5,000 recipients and dials them as capacity frees up.

You are responsible for complying with the regulations that apply to your calls, including the Telephone Consumer Protection Act (TCPA). See Cartesia’s Acceptable Use Policy.

curl -X POST "https://api.cartesia.ai/agents/calls" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
    "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
    "ringing_timeout_seconds": 30,
    "outbound_calls": [
      {
        "to_number": "+14155559876",
        "metadata": { "customer_id": "cust_123" }
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.cartesia.ai/agents/calls",
    headers={
        "X-API-Key": "YOUR_CARTESIA_API_KEY",
        "Cartesia-Version": "2026-08-14",
        "Content-Type": "application/json",
    },
    json={
        "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
        "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
        "ringing_timeout_seconds": 30,
        "outbound_calls": [
            {"to_number": "+14155559876", "metadata": {"customer_id": "cust_123"}}
        ],
    },
)
response.raise_for_status()
print(response.json()["calls"][0]["agent_call_id"])

Response

{
  "calls": [
    {
      "number": "+14155559876",
      "agent_call_id": "ac_3kF9mN2pQ8rT1vX6"
    }
  ]
}

The API returns 200 when the request is accepted. The calls array has one entry per destination, in the same order. Each entry carries either an agent_call_id or an error, so check every entry rather than the response status alone. Use agent_call_id with Get Call to follow the call. ringing_timeout_seconds sets how long each destination rings before the attempt times out, from 5 to 80 seconds. The default is 60. metadata accepts a JSON object that is stored on the call record.

Cartesia numbers place at most one outbound call per second. Faster requests are queued.