> ## Documentation Index > Fetch the complete documentation index at: https://docs.telleo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a batch > Queues up to 1,000 calls in one request. Each row is checked on its own: valid rows are queued, invalid rows come back in `rejected` with the row's `index`. Batch calls are dialled as lines free up, behind single calls. Scope: `calls:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /batches openapi: 3.1.0 info: title: Telleo API version: 1.0.0 description: Start AI phone calls from your own systems and get each call's outcome back. servers: - url: https://api.telleo.ai/v1 security: - ApiKey: [] tags: - name: Calls - name: Batches - name: Agents - name: Webhook paths: /batches: post: tags: - Batches summary: Start a batch description: >- Queues up to 1,000 calls in one request. Each row is checked on its own: valid rows are queued, invalid rows come back in `rejected` with the row's `index`. Batch calls are dialled as lines free up, behind single calls. Scope: `calls:write`. operationId: createBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBatch' example: agent_id: 17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c calls: - phone_number: '+919876543210' contact: name: Asha Verma external_id: lead-8812 variables: course: NEET 2027 - phone_number: '+919812345678' contact: name: Rohan Das external_id: lead-8813 variables: course: JEE 2027 responses: '201': description: The batch was created. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/BatchCreated' '400': description: >- The batch itself is not valid (no rows, more than 1,000 rows, unknown agent). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: error: code: invalid_request message: A batch holds at most 1000 calls; split it. request_id: req_8f2c1a7e '401': description: The key is missing, unknown, revoked or expired. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_api_key: value: error: code: missing_api_key message: Send your API key in the X-API-Key header. request_id: req_8f2c1a7e invalid_api_key: value: error: code: invalid_api_key message: This API key is not valid. request_id: req_8f2c1a7e '402': description: Out of credits. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_credits: value: error: code: insufficient_credits message: >- This account is out of AI calling credits. Top up to place calls. request_id: req_8f2c1a7e '403': description: The key lacks the scope this request needs. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_scope: value: error: code: insufficient_scope message: This key does not have the calls:write scope. request_id: req_8f2c1a7e '404': description: The agent does not exist. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: agent_not_found: value: error: code: agent_not_found message: No agent … in this account. request_id: req_8f2c1a7e '429': description: Too many requests for this key. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: code: rate_limited message: Too many requests. Retry after 12 seconds. request_id: req_8f2c1a7e components: schemas: CreateBatch: type: object required: - agent_id - calls properties: agent_id: type: string description: Default agent for every row. test: type: boolean default: false calls: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/CallInput' BatchCreated: type: object properties: id: type: string example: batch_2b9e0c1d4f6a8e7c5b3a1d0f object: type: string const: batch agent_id: type: string test: type: boolean accepted_count: type: integer rejected_count: type: integer calls: type: array items: type: object properties: index: type: integer id: type: string phone_number: type: string external_id: type: string rejected: type: array items: type: object properties: index: type: integer phone_number: type: string code: type: string enum: - invalid_request - duplicate_in_batch - call_already_queued - call_failed message: type: string call_id: type: string description: >- For `call_already_queued`: the call already waiting for this number. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable code. Branch on this, not on the message. example: invalid_request message: type: string description: A sentence you can log or show to an operator. request_id: type: string description: Quote this when you contact support. details: type: object additionalProperties: true description: >- Extra context, e.g. `errors: [{field, message}]` for validation errors or `call_id` for conflicts. CallInput: type: object required: - phone_number properties: agent_id: type: string description: >- The agent that makes the call. Required on `POST /calls`; on a batch row it overrides the batch's `agent_id`. List yours with `GET /agents`. phone_number: type: string description: >- E.164, e.g. `+919876543210`. Spaces, dashes, dots and brackets are ignored; a leading `00` is read as `+`. example: '+919876543210' contact: $ref: '#/components/schemas/Contact' variables: type: object maxProperties: 50 additionalProperties: type: - string - number - boolean description: >- Values for the `{{placeholders}}` in the agent's script. Keys: a letter, then letters, digits, `_` or spaces, at most 40 characters. Values: text, number or boolean, at most 500 characters. example: course: NEET 2027 city: Indore metadata: type: object additionalProperties: true description: >- Anything you want back on the call and its webhook (at most 8 KB as JSON). The agent never sees it. example: crm_owner: u_42 Contact: type: object properties: name: type: - string - 'null' maxLength: 120 description: >- How the agent addresses the person. Fills `{{name}}` in the agent's script. email: type: - string - 'null' format: email external_id: type: - string - 'null' maxLength: 255 description: >- Your own id for this person or lead (CRM record id). Echoed back and filterable on `GET /calls`. headers: RequestId: schema: type: string description: Unique id of this request. Quote it to support. securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: >- Your AI calling API key (`vak_call_…`). `Authorization: Bearer ` also works. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.