Skip to main content
Agents can make outbound dials with an API request. Simply specify a set of target phone numbers and your agent ID to place your dial.
ComplianceYou are solely responsible for remaining complaint 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/twilio/call/outbound" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CARTESIA_API_KEY" \
-H "Cartesia-Version: 2025-04-16" \
-d '{
  "target_numbers": ["YOUR_PHONE_NUMBER"],
  "agent_id": "YOUR_AGENT_ID",
  "metadata": {
    "customer_id": "cust_123",
    "custom_prompt": "Be extra friendly"
  }
}'
The metadata field accepts any JSON object up to 1MB. 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(...)
You are limited to one outbound dial placed per second, any requests faster than one dial per second will be queued.