> ## 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. # List calls > Your calls, newest first. Filter by batch, by your `external_id`, or by creation time; page with `starting_after`. Scope: `calls:read`. ## OpenAPI ````yaml /api-reference/openapi.json get /calls 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: /calls: get: tags: - Calls summary: List calls description: >- Your calls, newest first. Filter by batch, by your `external_id`, or by creation time; page with `starting_after`. Scope: `calls:read`. operationId: listCalls parameters: - name: batch_id in: query schema: type: string - name: external_id in: query schema: type: string description: Calls for one of your records. - name: created_after in: query schema: type: string format: date-time description: ISO-8601 instant, e.g. `2026-10-13T09:00:00Z`. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - name: starting_after in: query schema: type: string description: The `id` of the last call on the previous page. responses: '200': description: A page of calls. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/CallList' '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 '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: headers: RequestId: schema: type: string description: Unique id of this request. Quote it to support. schemas: CallList: type: object properties: object: type: string const: list data: type: array items: $ref: '#/components/schemas/Call' has_more: type: boolean 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. Call: type: object properties: id: type: string example: call_6f1d2c9a8b7e4f3a2d1c0b9a object: type: string const: call status: type: string enum: - queued - dialing - in_progress - completed - no_answer - busy - failed - canceled - expired status_reason: type: string description: >- Why a call is waiting or did not happen, in plain words. Present only when there is one. scheduled_for: type: string format: date-time description: >- Present while a queued call is held until a later time (outside calling hours, a recall gap, the daily limit). agent_id: type: string phone_number: type: string contact: $ref: '#/components/schemas/Contact' variables: type: object additionalProperties: true metadata: type: object additionalProperties: true batch_id: type: - string - 'null' test: type: boolean duration_seconds: type: - integer - 'null' created_at: type: string format: date-time dialed_at: type: - string - 'null' format: date-time ended_at: type: - string - 'null' format: date-time recording_url: type: - string - 'null' description: >- A temporary link to the recording. Fetch the call again for a fresh link after `recording_expires_at`. recording_expires_at: type: - string - 'null' format: date-time outcome: $ref: '#/components/schemas/Outcome' idempotent_replay: type: boolean description: >- Only on `POST /calls`: `true` when this is the call created by an earlier request with the same `Idempotency-Key`. 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`. Outcome: type: - object - 'null' description: >- What the AI took from the conversation. `null` until it has been processed (usually within a minute of the call ending), and for calls that did not connect. properties: disposition: type: - string - 'null' description: >- The agent's label for how the call went, from the dispositions configured on the agent (e.g. Interested, Not interested, Call back later). summary: type: - string - 'null' answers: type: object additionalProperties: true description: Each of the agent's extraction questions and the answer given. lead_rating: type: - integer - 'null' minimum: 1 maximum: 10 description: >- The AI's 1–10 score of the contact's interest; `null` when it could not tell. callback_requested: type: boolean callback_time_text: type: - string - 'null' description: >- When the contact asked to be called back, in their words (e.g. `tomorrow after 6 pm`). follow_up: type: - string - 'null' enum: - CALL - CALL_LATER - SKIP - null description: >- Whether a person should call this contact: `CALL` (now), `CALL_LATER` or `SKIP`. `null` when not assessed; never read `null` as `CALL`. follow_up_note: type: - string - 'null' description: >- One sentence on why, for the person deciding whether to call (at most 240 characters). meeting: type: object description: >- A meeting, demo, visit or callback the contact AGREED to at a specific day or time. `requested` is false when no time was agreed. properties: requested: type: boolean at: type: - string - 'null' description: >- ISO-8601 with offset, resolved from what was said, e.g. `2026-10-14T18:00:00+05:30`. time_text: type: - string - 'null' description: The contact's own words, e.g. `tomorrow 6 pm`. type: type: - string - 'null' description: '`demo`, `visit`, `call` or `meeting`.' transcript: type: array items: type: object properties: speaker: type: string enum: - agent - contact text: type: string 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.