---
title: "Query agents with filters, sorting and pagination"
method: POST
path: "/api/v1/agentic/agents/query"
tags: ["Agentic - Agents"]
---

# Query agents with filters, sorting and pagination

`POST /api/v1/agentic/agents/query`

## Request

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

Retrieve a list of AI agents with advanced filtering, sorting, and pagination. Access complete agent configurations including prompts, settings, and integrations.

**Query Capabilities:**
- Filter by agent type (prompt-based, analysis-agent, ai-assistant, node-based)
- Search by name or system prompt content
- Filter by language or capabilities
- Sort by any field (name, creation date, last modified, etc.)
- Paginate with `limit` and `nextId`

**Response Includes:**
- Agent configuration (name, type, prompts)
- Phone and email settings
- Voice configuration and language
- Connected knowledge bases and workflows
- Integration settings
- Appointment settings

**Common Use Cases:**
- List all customer-facing agents
- Find agents by capability or language
- Export agent configurations
- Audit agent settings across organization

## Headers

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

## Request body

- object
  - `pagedListRequest` object
    - `nextId` string, nullable: The ID of the next page
    - `pageSize` integer: The number of items per page
  - `queryOptionsRequest` object
    - `filtersRequest` object[]: The list of filters to be applied
      - `field` string, required: The name of the column filter is going to be applied on
      - `matchMode` integer, required: The mode of the filter, which determines how the filter is applied. Possible values include: - Equal: Matches values that are exactly the same. - NotEqual: Matches values that are not the same. - LessThan: Matches values that are less than the specified value. - LessThanOrEqual: Matches values that are less than or equal to the specified value. - GreaterThan: Matches values that are greater than the specified value. - GreaterThanOrEqual: Matches values that are greater than or equal to the specified value. - Like: Matches values that are similar to the specified pattern. - Contains: Matches values that contain the specified substring. - NotContains: Matches values that do not contain the specified substring. - Any: Matches any value. - Between: Matches values that fall within a specified range. - In: Matches values that are within a specified set. - NotIn: Matches values that are not within a specified set. - StartsWith: Matches values that start with the specified substring. - EndsWith: Matches values that end with the specified substring. Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, Like, Contains, Any, Between, In, NotIn, NotContains, StartsWith, EndsWith, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
      - `operator` integer, nullable: The operator of the filter, which determines how multiple filters are combined. Possible values include: - And: All specified filters must be satisfied. - Or: At least one of the specified filters must be satisfied. And, Or, 1, 2
      - `value` unknown
      - `values` unknown[], nullable: The values against which the filter is going to be applied (array items can be any type)
        - unknown
      - `rangeValues` object, nullable: The range of values to be checked between
        - `start` unknown
        - `end` unknown
      - `ignoreCase` boolean, nullable: Whether case should be ignored or not
    - `sortRequest` object[]: The list of sort requests
      - `field` string, required: The name of the column to be sorted
      - `direction` integer, required: The direction of sorting, which indicates how the results should be ordered. Possible values include: - Ascending (0): Sorts the results from the lowest to the highest value. - Descending (1): Sorts the results from the highest to the lowest value. Ascending, Descending, 0, 1
      - `priority` integer, required: The priority of sorting
    - `includes` string[]: The list of table names whose records are needed to be fetched along with current table's records
    - `selectFields` string[]: The list of field names that should be included in the response. If not specified, all fields will be returned. Note: Essential fields like _id, createdAt, companyId, etc. are always included for proper toResponse() functionality.

## Response `200`

Agents retrieved successfully with pagination

- 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

- `400`: Bad request - Invalid query parameters
- `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)