> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zudu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List calls

> Lists or filters calls (current behavior).

## Notes

* This is the **main** endpoint for listing/filtering calls.


## OpenAPI

````yaml post /api/calls
openapi: 3.0.3
info:
  title: Zudu API
  description: >-
    Comprehensive REST API for LiveKit Backend - Call Management, Agent
    Configuration, and Real-time Communication Services
  version: 1.0.0
  contact:
    name: Zudu AI Team
    url: https://zudu.ai
    email: support@zudu.ai
  license:
    name: Proprietary
    url: https://zudu.ai/license
servers:
  - url: https://api.zudu.ai
    description: Production (Customer-facing)
security:
  - apiKey: []
    apiSecret: []
tags:
  - name: Agent Management
    description: Create and manage AI agents
  - name: Call Data Management
    description: Call records and history
  - name: Customer API Keys
    description: Manage API keys
  - name: Post-Call Webhooks
    description: Webhook configuration
  - name: phone-number-controller
    description: Phone numbers
  - name: batch-call-controller
    description: Batch calls
  - name: MCP Server Management
    description: MCP servers
  - name: Knowledge Base Management
    description: Knowledge bases
  - name: Call Analysis
    description: Call analysis
paths:
  /api/calls:
    post:
      tags:
        - Call Data Management
      summary: List calls with pagination and filtering
      description: >-
        Retrieves a paginated list of calls for the organization with optional
        filtering by status, date range, and other criteria.
      operationId: listCalls
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Optional filters and pagination parameters
              properties:
                page:
                  type: integer
                  description: Page number (0-based indexing)
                  example: 0
                limit:
                  type: integer
                  description: Items per page (1-100)
                  example: 20
                sort_by:
                  type: string
                  description: >-
                    Field to sort by (e.g., start_timestamp, end_timestamp,
                    call_duration, call_id)
                  example: start_timestamp
                sort_order:
                  type: string
                  description: Sort direction (ascending or descending)
                  example: descending
                filter_criteria:
                  type: object
                  description: Filtering criteria for calls
                  additionalProperties: true
              additionalProperties: false
            example:
              page: 0
              limit: 50
              sort_by: start_timestamp
              sort_order: descending
              filter_criteria:
                call_status:
                  - ongoing
                  - ended
                  - registered
                agent_id:
                  - agent-123
                  - agent-456
                duration_ms:
                  lower_threshold: 30000
                  upper_threshold: 300000
                transcript_search: help support
      responses:
        '200':
          description: Calls retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                message: Calls retrieved successfully
                status: success
                error: null
                data:
                  organization_id: org-789
                  calls:
                    - id: 550e8400-e29b-41d4-a716-446655440000
                      call_id: call-456
                      agent_id: agent-123
                      organization_id: org-789
                      call_status: ENDED
                      call_type: PHONE_CALL
                      direction: OUTBOUND
                      from_number: '+0987654321'
                      to_number: '+1234567890'
                      start_timestamp: 1703097600000
                      end_timestamp: 1703098200000
                      call_duration: 600000
                  pagination:
                    page: 0
                    limit: 50
                    total_count: 25
                    total_pages: 1
                    has_next_page: false
                    has_previous_page: false
                  returned_count: 1
                  sort_order: descending
                  sort_by: start_timestamp
                  applied_filters:
                    duration_ms:
                      lower_threshold: 30000
                      upper_threshold: 300000
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ApiResponseMapStringObject'
      security:
        - apiKey: []
          apiSecret: []
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
        error:
          type: string
        data:
          type: object
    ApiResponseMapStringObject:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
        error:
          type: string
        data:
          type: object
          additionalProperties:
            type: object
  responses:
    BadRequest:
      description: Bad request
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key for MCP server and external service authentication
      name: X-API-KEY
      in: header
    apiSecret:
      type: apiKey
      description: API Secret for MCP server and external service authentication
      name: X-API-SECRET
      in: header

````