curl --request POST \
--url https://api.cartesia.ai/agents/calls \
--header 'Authorization: Bearer <token>' \
--header 'Cartesia-Version: <cartesia-version>' \
--header 'Content-Type: application/json' \
--data '
{
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
'import requests
url = "https://api.cartesia.ai/agents/calls"
payload = {
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
headers = {
"Cartesia-Version": "<cartesia-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Cartesia-Version': '<cartesia-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
from_number_id: '<string>',
agent_id: '<string>',
outbound_calls: [{to_number: '<string>', metadata: {}}],
ringing_timeout_seconds: 42,
max_call_duration_minutes: 123
})
};
fetch('https://api.cartesia.ai/agents/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cartesia.ai/agents/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from_number_id' => '<string>',
'agent_id' => '<string>',
'outbound_calls' => [
[
'to_number' => '<string>',
'metadata' => [
]
]
],
'ringing_timeout_seconds' => 42,
'max_call_duration_minutes' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Cartesia-Version: <cartesia-version>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cartesia.ai/agents/calls"
payload := strings.NewReader("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Cartesia-Version", "<cartesia-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cartesia.ai/agents/calls")
.header("Cartesia-Version", "<cartesia-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartesia.ai/agents/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}"
response = http.request(request)
puts response.read_body{
"calls": [
{
"number": "<string>",
"agent_call_id": "<string>",
"error": {}
}
]
}Create Outbound Call
curl --request POST \
--url https://api.cartesia.ai/agents/calls \
--header 'Authorization: Bearer <token>' \
--header 'Cartesia-Version: <cartesia-version>' \
--header 'Content-Type: application/json' \
--data '
{
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
'import requests
url = "https://api.cartesia.ai/agents/calls"
payload = {
"from_number_id": "<string>",
"agent_id": "<string>",
"outbound_calls": [
{
"to_number": "<string>",
"metadata": {}
}
],
"ringing_timeout_seconds": 42,
"max_call_duration_minutes": 123
}
headers = {
"Cartesia-Version": "<cartesia-version>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Cartesia-Version': '<cartesia-version>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
from_number_id: '<string>',
agent_id: '<string>',
outbound_calls: [{to_number: '<string>', metadata: {}}],
ringing_timeout_seconds: 42,
max_call_duration_minutes: 123
})
};
fetch('https://api.cartesia.ai/agents/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cartesia.ai/agents/calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from_number_id' => '<string>',
'agent_id' => '<string>',
'outbound_calls' => [
[
'to_number' => '<string>',
'metadata' => [
]
]
],
'ringing_timeout_seconds' => 42,
'max_call_duration_minutes' => 123
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Cartesia-Version: <cartesia-version>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cartesia.ai/agents/calls"
payload := strings.NewReader("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Cartesia-Version", "<cartesia-version>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cartesia.ai/agents/calls")
.header("Cartesia-Version", "<cartesia-version>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartesia.ai/agents/calls")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Cartesia-Version"] = '<cartesia-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from_number_id\": \"<string>\",\n \"agent_id\": \"<string>\",\n \"outbound_calls\": [\n {\n \"to_number\": \"<string>\",\n \"metadata\": {}\n }\n ],\n \"ringing_timeout_seconds\": 42,\n \"max_call_duration_minutes\": 123\n}"
response = http.request(request)
puts response.read_body{
"calls": [
{
"number": "<string>",
"agent_call_id": "<string>",
"error": {}
}
]
}Authorizations
Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.
Headers
API version header.
2026-03-01 "2026-03-01"
Body
Request body for starting outbound calls from an agent phone number.
Phone number ID to place calls from. The attached provider handles outbound calling for this number.
Agent that handles the outbound calls.
Per-call destination and metadata configuration. Every destination dials immediately, so destinations beyond the organization's agent-call concurrency limit are rejected rather than queued. For larger lists, use POST /agents/calls/batches instead.
1Show child attributes
Show child attributes
Seconds to wait for the callee to answer before giving up. Omit to use the default (60 seconds).
5 <= x <= 80Optional maximum call duration in minutes.
Response
Outbound call requests accepted. Destinations succeed or fail individually, so check each calls entry for an error rather than relying on the status code alone.
Result for one destination, carrying either an agent_call_id or an error.
- AgentOutboundCallItemResponse
- AgentOutboundCallItemResponse
Show child attributes
Show child attributes
Was this page helpful?