Skip to main content
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.
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": "call_3kF9mN2pQ8rT1vX6"
#     }
#   ]
# }
The API returns 200 when the request is accepted. The calls array has one entry per outbound_calls item, in the same order. 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.