> ## 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. # Create Call Batch > Queues a batch of outbound calls. Calls are issued gradually, subject to the organization's and the batch's concurrency limits. ## OpenAPI ````yaml latest.yml POST /agents/calls/batches openapi: 3.0.1 info: title: Cartesia API version: 0.0.1 servers: - url: https://api.cartesia.ai description: Production security: [] paths: /agents/calls/batches: post: tags: - Agents summary: Create Call Batch description: >- Queues a batch of outbound calls. Calls are issued gradually, subject to the organization's and the batch's concurrency limits. operationId: agents_create-call-batch parameters: - $ref: '#/components/parameters/CartesiaVersionHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentCallBatchRequest' responses: '201': description: The created batch, with all of its call requests queued. content: application/json: schema: $ref: '#/components/schemas/AgentCallBatch' '400': description: >- Invalid request body, missing required fields, an invalid recipient (missing or non-E.164 `to_number`, oversized `metadata`), an invalid call configuration, an invalid `scheduled_at`, a `target_concurrency_limit` that exceeds the organization's concurrency limit, or a phone number that cannot place outbound calls. '402': description: >- The organization has reached its agents usage limit. Upgrade the subscription or enable overages. '404': description: Agent or phone number not found. '500': description: The batch could not be created. security: - APIKeyAuth: [] components: parameters: CartesiaVersionHeader: name: Cartesia-Version in: header description: API version header. required: true schema: type: string format: date example: '2026-03-01' enum: - '2026-03-01' schemas: AgentCallBatchRequest: title: AgentCallBatchRequest type: object description: Request body for queueing a batch of outbound calls. properties: name: type: string description: A label for the batch. agent_id: type: string description: The identifier of the agent that handles the batch's calls. from_number_id: type: string description: >- The identifier of the phone number to place calls from. The attached provider handles outbound calling for this number. recipients: type: array minItems: 1 maxItems: 5000 items: $ref: '#/components/schemas/AgentOutboundCallItem' description: >- Per-call destination and metadata configuration. Up to 5,000 recipients per batch. target_concurrency_limit: type: integer minimum: 1 description: >- 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_seconds: type: integer minimum: 5 maximum: 80 description: >- Seconds to wait for the callee to answer before giving up. Omit to use the default (60 seconds). max_call_duration_minutes: type: integer minimum: 1 maximum: 480 description: >- Maximum call duration in minutes. Omit to use the default (480 minutes). scheduled_at: type: string format: date-time description: >- 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. required: - name - agent_id - from_number_id - recipients AgentCallBatch: title: AgentCallBatch type: object properties: id: type: string description: The unique identifier for the batch. name: type: string description: The batch's label. agent_id: type: string description: The identifier of the agent that handles the batch's calls. from_number_id: type: string description: The identifier of the phone number the batch dials from. region: type: string enum: - US - EU - APAC description: The deployment region whose dispatcher drains the batch. target_concurrency_limit: type: integer description: Maximum number of calls from this batch dialed concurrently. status: $ref: '#/components/schemas/AgentCallBatchStatus' description: >- The batch's lifecycle status, derived at read time from dispatch progress. | Status | Meaning | | --- | --- | | `pending` | No calls dispatched yet | | `in_progress` | Some calls dispatched, not all | | `completed` | All recipients dispatched | | `failed` | All recipients failed before dialing | | `cancelled` | Cancelled before every call was dispatched | total_calls_scheduled: type: integer description: Total recipients queued in the batch. total_calls_dispatched: type: integer description: >- Recipients handed to the dialer so far, including those that failed before a call could be placed. total_calls_finished: type: integer description: >- Recipients whose latest call attempt reached a terminal state (completed or failed), including pre-dial failures. retry_count: type: integer description: >- Number of times the batch has been retried. `0` until the first retry. created_at: type: string format: date-time description: When the batch was created. last_updated_at: type: string format: date-time description: When the batch was last updated. scheduled_at: type: string format: date-time description: >- The scheduled dispatch time, in RFC3339 UTC format. Omitted for batches that dispatch immediately. admitted_at: type: string format: date-time description: >- The actual dispatch time, in RFC3339 UTC format. The batch may stay unadmitted in the queue due to scheduling or unavailable concurrency. recipients: type: array items: $ref: '#/components/schemas/AgentCallBatchRecipient' description: >- The batch's recipients. Returned only on `GET /agents/calls/batches/{batch_id}`. required: - id - name - agent_id - from_number_id - region - target_concurrency_limit - status - total_calls_scheduled - total_calls_dispatched - total_calls_finished - retry_count - created_at - last_updated_at AgentOutboundCallItem: title: AgentOutboundCallItem type: object description: Destination and metadata for one outbound call. properties: to_number: type: string description: >- Destination phone number for this outbound call, in E.164 format (e.g., `+14155559876`). metadata: type: object nullable: true additionalProperties: true description: Custom metadata passed to the agent code deployment. required: - to_number AgentCallBatchStatus: title: AgentCallBatchStatus type: string enum: - pending - in_progress - completed - failed - cancelled description: >- The lifecycle status of a batch, derived at read time from dispatch progress. AgentCallBatchRecipient: title: AgentCallBatchRecipient type: object description: >- One recipient within a batch and its current status. Returned only on batch detail reads. properties: id: type: string description: The unique identifier for the recipient within the batch. to_number: type: string description: Destination phone number, in E.164 format (e.g., `+14155559876`). status: $ref: '#/components/schemas/AgentCallBatchRecipientStatus' description: >- The recipient's current status. Before dispatch it reflects the queue state; after dispatch it reflects the latest call attempt. | Status | Meaning | | --- | --- | | `queued` | Waiting for the dispatcher | | `dispatched` | Handed to the dialer; no call attempt has connected or finished yet | | `started` | Call connected and in progress | | `completed` | Call connected and ended successfully | | `failed` | The call could not be placed (see `error_message`), or the latest attempt failed | | `cancelled` | Batch was cancelled before this recipient was dialed | agent_call_id: type: string description: >- The agent call ID, used to fetch per-call information via [Get Call](/api-reference/agents/calls/get-call). Set once the call has been dispatched. end_reason: $ref: '#/components/schemas/EndReason' description: The reason why the call ended. error_message: type: string description: >- Why the request failed before a call could be placed. Returned in place of `agent_call_id` when the recipient never reached a dial attempt. metadata: type: object nullable: true additionalProperties: true description: Custom metadata passed to the agent code deployment. created_at: type: string format: date-time description: When the recipient was queued. required: - id - to_number - status - created_at AgentCallBatchRecipientStatus: title: AgentCallBatchRecipientStatus type: string description: >- The status of a recipient within a batch. Before dispatch it reflects the queue state; after dispatch it reflects the latest call attempt. EndReason: title: EndReason type: string enum: - agent_hangup - client_hangup - api_cancelled - max_duration - inactivity - client_disconnected - dial_busy - dial_failed - dial_no_answer - error description: A machine-readable enum indicating why a call ended. securitySchemes: APIKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- Cartesia API key (`sk_car_...`). Get one at [play.cartesia.ai/keys](https://play.cartesia.ai/keys). ````