Agents

Cancel Call Batch

Stops dialing the batch's queued calls. Calls already in flight are left to finish. Idempotent.

post/agents/calls/batches/{batch_id}/cancel

Path parameters

batch_idstring required

The ID of the batch.

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

Example:2026-03-01

API version header.

The batch was cancelled.

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.