---
title: "Query calls with filters, sorting and pagination"
method: POST
path: "/api/v1/phones/calls/query"
tags: ["Phones - Calls"]
---

# Query calls with filters, sorting and pagination

`POST /api/v1/phones/calls/query`

## Request

- Base URL: `https://api.voicelogica.ai`
- URL: `https://api.voicelogica.ai/api/v1/phones/calls/query`
- Auth: API key in header `x-api-key`

Retrieve call records with advanced filtering, sorting, and pagination. Access detailed call information including recordings, transcriptions, AI analysis, and call metadata.

**Query Capabilities:**
- Filter by call status (completed, failed, in_progress, scheduled, etc.)
- Filter by date range (createdAt) using `matchMode: 10` (Between)
- Search by phone numbers (destination or source)
- Filter by agent, user, or campaign
- Sort by any field (date, duration, status, etc.)
- Paginate with `pageSize` and `nextId`

**Filter Match Modes:**
- `1`: Equal - Exact match
- `2`: NotEqual - Not equal to value
- `3`: LessThan - Less than value
- `4`: LessThanOrEqual - Less than or equal to value
- `5`: GreaterThan - Greater than value
- `6`: GreaterThanOrEqual - Greater than or equal to value
- `7`: Like - Pattern matching (SQL LIKE)
- `8`: Contains - Field contains value
- `10`: Between - Value is between range (use `rangeValues` with `start` and `end`)
- `11`: In - Value is in array (use `values` array)

**Common Filter Fields:**
- `createdAt`: Call creation timestamp (ISO 8601 date string) - use for date range queries
- `status`: Call status (answered, failed, missed, in_call, etc.)
- `phoneNumber`: Destination phone number
- `agentId`: AI agent that handled the call
- `callDirection`: inbound or outbound
- `duration`: Call duration in seconds
- `source`: Call source (api, web, phone, scheduled, campaign, workflow)

**Example Request:**
The example below shows how to query calls from January 2024 with status "answered", sorted by creation date descending.

**Response Includes:**
- Call details (duration, status, timestamps)
- Phone numbers (source and destination)
- Contactd agent or user information
- Recording and transcription URLs
- AI analysis and summary
- Dynamic variables and metadata
- Call direction (inbound/outbound)

**Common Use Cases:**
- Export call logs for reporting
- Find all failed calls for retry
- Get calls for a specific customer or agent
- Retrieve calls within a date range for analytics

## Headers

- `x-api-key` string, required
- `x-company-id` string

## Request body

- object: Request schema for querying calls with filters, sorting, and pagination
  - `pagedListRequest` object, required: Pagination settings
    - `nextId` string, nullable: ID of the next page for cursor-based pagination. Use null for the first page, then use the ID returned in the response for subsequent pages.
    - `pageSize` integer: Number of calls to return per page (default: 50, max: 100)
  - `queryOptionsRequest` object, required: Query filter, sort, and include options
    - `filtersRequest` object[], required: List of filters to apply to the query
      - `field` string, required: Field name to filter on (e.g., "createdAt", "status", "phoneNumber", "agentId", "callDirection")
      - `matchMode` number, required: Filter match mode: 1=Equal, 2=NotEqual, 3=LessThan, 4=LessThanOrEqual, 5=GreaterThan, 6=GreaterThanOrEqual, 7=Like, 8=Contains, 10=Between (for date ranges), 11=In
      - `operator` number, nullable: Logical operator between multiple filters: 1=AND, 2=OR
      - `value` object, nullable: Single value to filter against (for Equal, Like, etc.)
      - `values` object[], nullable: Array of values for In operations
      - `rangeValues` object, nullable: Range values for Between operations (used for date ranges)
        - `start` object, required: Start value of the range (ISO 8601 date string for date fields)
        - `end` object, required: End value of the range (ISO 8601 date string for date fields)
      - `ignoreCase` boolean, nullable: Whether to perform case-insensitive comparison
    - `sortRequest` object[], required: List of sort operations to apply
      - `field` string, required: Field name to sort by (e.g., "createdAt", "duration", "status")
      - `direction` number, required: Sort direction: 0=Ascending, 1=Descending
      - `priority` integer, required: Sort priority when multiple sort fields are specified (lower number = higher priority)
    - `includes` string[], required: Related entities to include in the response: "agent", "contact", "voipPhone", "user", "recordingFile", "transcriptionFile", "campaign", "humanRecordingFile", "humanTranscriptionFile"
    - `selectFields` string[], required: Specific fields to return in the response. Leave empty to return all fields.
    - `excludeFields` string[]: Fields to leave out (ignored when selectFields is set), e.g. "messages", "aiDialogue". "agent.systemPrompt" slims an included record.

## Response `200`

Got paginated result successfully

- object
  - `data` unknown[], required: Array of response data
    - unknown
  - `total` integer, required: Total number of records
  - `nextId` string, nullable: ID of the next page, if available
  - `currentTotal` integer, required: Number of records in the current response

## Other responses

- `401`: Unauthorized
- `403`: Invalid CSRF
- `429`: Rate limit exceeded
- `500`: Internal Server Error

---

[API](https://skmtc.dev/voicelogica/apis/voice-logica-api.md) · [All operations](https://skmtc.dev/voicelogica/apis/voice-logica-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voicelogica/apis/voice-logica-api/revisions/30f76840084e?raw)