CAcartesia
Agents

Create Call Batch

Queues a batch of outbound calls. Calls are issued gradually, subject to the organization's and the batch's concurrency limits.

post/agents/calls/batches

Request

Headers

Cartesia-Version'2026-03-01' date required
Example:2026-03-01

API version header.

Request body

namestring required

A label for the batch.

agent_idstring required

The identifier of the agent that handles the batch's calls.

from_number_idstring required

The identifier of the phone number to place calls from. The attached provider handles outbound calling for this number.

target_concurrency_limitinteger

Maximum number of calls from this batch to dial concurrently. Must not exceed the organization's concurrency limit. Omit to default to half of the organization's agent-call concurrency limit, leaving headroom for other calls.

ringing_timeout_secondsinteger

Seconds to wait for the callee to answer before giving up. Omit to use the default (60 seconds).

max_call_duration_minutesinteger

Maximum call duration in minutes. Omit to use the default (480 minutes).

scheduled_atstring date-time

When to start dispatching the batch, as an RFC3339 timestamp with a timezone offset (e.g. 2026-06-15T16:00:00Z). Must be in the future and within 30 days. Omit to dispatch immediately.

region'US' | 'EU' | 'APAC'

The region from which the batch's outbound calls are dispatched. Valid only when from_number_id is a SIP-trunk number; rejected for other telephony account types. Omit to derive the region from the telephony account.

Response

The created batch, with all of its call requests queued.

idstring required

The unique identifier for the batch.

namestring required

The batch's label.

agent_idstring required

The identifier of the agent that handles the batch's calls.

from_number_idstring required

The identifier of the phone number the batch dials from.

region'US' | 'EU' | 'APAC' required

The deployment region whose dispatcher drains the batch.

target_concurrency_limitinteger required

Maximum number of calls from this batch dialed concurrently.

status'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' required

The lifecycle status of a batch, derived at read time from dispatch progress.

total_calls_scheduledinteger required

Total recipients queued in the batch.

total_calls_dispatchedinteger required

Recipients handed to the dialer so far, including those that failed before a call could be placed.

total_calls_finishedinteger required

Recipients whose latest call attempt reached a terminal state (completed or failed), including pre-dial failures.

retry_countinteger required

Number of times the batch has been retried. 0 until the first retry.

created_atstring date-time required

When the batch was created.

last_updated_atstring date-time required

When the batch was last updated.

scheduled_atstring date-time

The scheduled dispatch time, in RFC3339 UTC format. Omitted for batches that dispatch immediately.

admitted_atstring date-time

The actual dispatch time, in RFC3339 UTC format. The batch may stay unadmitted in the queue due to scheduling or unavailable concurrency.

Changes

No recorded changes to this operation across all 1 revision of this API.