> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound Calling

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](/line/integrations/telephony/phone-numbers#assigning-an-agent), and any agent can place calls from it.

<Warning title="Compliance" icon="triangle-exclamation">
  **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](https://cartesia.ai/legal/acceptable-use.html) for more detail.
</Warning>

<CodeGroup>
  ```bash Bash theme={null}
  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"
  #     }
  #   ]
  # }
  ```

  ```python Python theme={null}
  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": "call_3kF9mN2pQ8rT1vX6",
  #     }
  #   ]
  # }
  print(body["calls"][0]["agent_call_id"])
  ```

  ```bash CLI theme={null}
  # Trigger an outbound call from a deployed agent to a specific number
  cartesia call <phone_number> <agent_id>
  ```
</CodeGroup>

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](/api-reference/agents/calls/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.

```python theme={null}
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(...)
```

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