Outbound Calling - Cartesia Docs

Agents can make outbound calls with an API request. Specify a set of target phone numbers in E.164 format (e.g., +14155559876) and your agent ID to place the call. The 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 place calls from it.

Placing many calls at once?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.

ComplianceYou 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.

curl -X POST "https://api.cartesia.ai/agents/calls" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -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"
        }
      }
    ]
  }'

# Response (200)
# {
#   "calls": [
#     {
#       "number": "+14155559876",
#       "agent_call_id": "ac_3kF9mN2pQ8rT1vX6"
#     }
#   ]
# }

import requests

url = "https://api.cartesia.ai/agents/calls"

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

payload = {
    "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
    "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
    "ringing_timeout_seconds": 30,
    "outbound_calls": [
        {
            "to_number": "+14155559876",
            "metadata": {
                "customer_id": "cust_123",
            },
        }
    ],
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
body = response.json()

# Response (200)
# {
#   "calls": [
#     {
#       "number": "+14155559876",
#       "agent_call_id": "ac_3kF9mN2pQ8rT1vX6",
#     }
#   ]
# }
print(body["calls"][0]["agent_call_id"])

# Trigger an outbound call from a deployed agent to a specific number
cartesia call <phone_number> <agent_id>

The API returns 200 when the request is accepted. The calls array has one entry per outbound_calls item, in the same order. Destinations succeed and fail independently, so each entry carries either an agent_call_id or an error — check every entry, not just the response status. Use agent_call_id to fetch per call information via Get Call. Set ringing_timeout_seconds (5–80) to control how long each destination rings before the call times out. Omit to use the default of 60 seconds. The metadata field accepts a JSON object. This data is passed to your agent code deployment and can be accessed to customize agent behavior per call. You can access the metadata in your agent code via the call_request.metadata object in your get_agent function.

async def get_agent(env, call_request):
    if call_request.metadata:
        logger.info(f"Received metadata: {call_request.metadata}")
    # Use metadata to customize agent behavior
    return LlmAgent(...)

For Cartesia phone numbers, you are limited to one outbound call per second; requests faster than one call per second are queued.