> ## Documentation Index > Fetch the complete documentation index at: https://docs.vatel.ai/llms.txt > Use this file to discover all available pages before exploring further. # List calls > Paginated calls for the organization tied to your API key. Filter with optional query parameters. When using the internal server API key (`Authorization: Bearer` or `API-KEY` matching server config), you must send `organization_id` as a query parameter (UUID). ## OpenAPI ````yaml get /v1/calls openapi: 3.0.3 info: title: Vatel AI REST API description: >- Programmatic access for agents, telephony, and session tokens. Send `Authorization: Bearer ` on all requests unless noted. Most error responses return JSON with an `error` string message. version: 0.2.4 servers: - url: https://api.vatel.ai description: Production security: - bearerAuth: [] tags: - name: organization description: Organization tied to your API key - name: llms description: LLM model identifiers - name: voices description: TTS voice catalog - name: agents description: Agents, outbound dial, agent versions - name: twilio description: Imported Twilio phone numbers - name: sip-trunks description: SIP trunk configuration - name: session description: Session tokens and voice WebSocket connections. - name: calls description: Call history, recordings, and live eavesdrop for your organization - name: eavesdrop description: Listen to live calls and send supervisor commands over WebSocket. paths: /v1/calls: get: tags: - calls summary: List calls description: >- Paginated calls for the organization tied to your API key. Filter with optional query parameters. When using the internal server API key (`Authorization: Bearer` or `API-KEY` matching server config), you must send `organization_id` as a query parameter (UUID). operationId: listCalls parameters: - name: organization_id in: query required: false description: >- Organization UUID. Required when the request is authenticated with the internal server API key; ignored for organization API keys. schema: type: string format: uuid - name: page in: query required: false description: Page number (1-based). Default 1. schema: type: integer minimum: 1 default: 1 - name: page_size in: query required: false description: Page size. Default 20, maximum 100. schema: type: integer minimum: 1 maximum: 100 default: 20 - name: agent_ids in: query required: false description: Comma-separated agent UUIDs to restrict results. schema: type: string - name: status in: query required: false schema: $ref: '#/components/schemas/CallStatus' - name: source in: query required: false schema: $ref: '#/components/schemas/CallSource' - name: date_from in: query required: false description: >- Filter calls with `created_at` on or after this instant (RFC3339 or ISO8601 string accepted by the backend). schema: type: string - name: date_to in: query required: false description: Filter calls with `created_at` on or before this instant. schema: type: string - name: outbound in: query required: false schema: type: string enum: - 'true' - 'false' - name: search in: query required: false description: Substring match on party number (max 256 characters). schema: type: string - name: tag in: query required: false description: Filter by tag (max 128 characters). schema: type: string - name: outcome in: query required: false description: Filter by termination outcome / reason bucket. schema: type: string enum: - transferred - agent_end - user_end responses: '200': description: Paginated calls content: application/json: schema: $ref: '#/components/schemas/PaginatedCallsResponse' '400': description: Invalid query parameters (e.g. invalid UUIDs or filter enums) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CallStatus: type: string description: Call lifecycle status. enum: - connected - started - in_progress - auth_failed - ended CallSource: type: string description: How the call entered the platform. enum: - twilio - sip - simulation - api PaginatedCallsResponse: type: object required: - calls - pagination properties: calls: type: array items: $ref: '#/components/schemas/Call' pagination: $ref: '#/components/schemas/PaginationInfo' ErrorResponse: type: object description: Standard error body for most non-2xx JSON responses on this API. required: - error properties: error: type: string description: Human-readable message; may include validation detail. Call: type: object description: >- Public call record. `cost` is the customer-facing (marked-up) total; raw provider cost is not exposed. properties: id: type: string format: uuid agent_id: type: string format: uuid graph_version_id: type: string format: uuid organization_id: type: string format: uuid party_number: type: string status: $ref: '#/components/schemas/CallStatus' source: $ref: '#/components/schemas/CallSource' termination_reason: type: string extracted_variables: type: array items: $ref: '#/components/schemas/ContextVariable' outbound: type: boolean outbound_contact_id: type: string format: uuid outbound_list_run_id: type: string format: uuid created_at: type: string description: RFC3339 timestamp connected_at: type: string description: RFC3339 timestamp when present started_at: type: string description: RFC3339 timestamp when present ended_at: type: string description: RFC3339 timestamp when present summary: type: string transcript: $ref: '#/components/schemas/Transcript' description: Conversation transcript. Omitted when not stored for the call. cost: type: number description: Marked-up total cost for the call. tags: type: array items: type: string duration_seconds: type: integer description: Approximate duration from started_at to ended_at when both are set. feedback: $ref: '#/components/schemas/CallFeedback' description: Caller feedback; omitted when not set. PaginationInfo: type: object required: - page - page_size - total - total_pages - has_next - has_prev properties: page: type: integer page_size: type: integer total: type: integer total_pages: type: integer has_next: type: boolean has_prev: type: boolean ContextVariable: type: object description: Extracted or session variable attached to a call. properties: name: type: string type: type: string enum: - system - input - extracted description: type: string value: description: JSON value; shape depends on dataType. dataType: type: string enum: - string - number - boolean - object - array rationale: type: string Transcript: type: object description: Ordered transcript for the call. required: - entries properties: entries: type: array items: $ref: '#/components/schemas/TranscriptEntry' CallFeedback: type: object description: Optional post-call feedback stored as JSON. required: - stars - notes properties: stars: type: integer notes: type: string TranscriptEntry: type: object description: >- One line in the call transcript (message, tool call, tool output, or interruption). properties: index: type: integer role: type: string description: >- For message rows: user, assistant, or system. May be empty for tool or interruption rows. message: type: string type: $ref: '#/components/schemas/TranscriptEntryType' toolCall: $ref: '#/components/schemas/TranscriptToolCall' toolCallOutput: type: string createdAt: type: string format: date-time durationMs: type: integer format: int64 turnId: type: string TranscriptEntryType: type: string description: Kind of transcript row. enum: - message - tool_call - tool_call_output - interruption TranscriptToolCall: type: object description: Tool invocation metadata on a transcript row. properties: itemId: type: string callId: type: string toolName: type: string arguments: type: string description: JSON string of arguments. output: type: string startedAt: type: string format: date-time endedAt: type: string format: date-time securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Send your organization API key as `Authorization: Bearer `.' ````