---
title: "POST /v2/list-agents"
method: POST
path: "/v2/list-agents"
---

# POST /v2/list-agents

`POST /v2/list-agents`

## Request

- Base URL: `https://api.retellai.com`
- URL: `https://api.retellai.com/v2/list-agents`
- Auth: HTTP bearer

List unique agents with pagination.

## Query parameters

- `limit` integer
- `sort_order` 'ascending' | 'descending'
- `pagination_key` string

## Request body

- object
  - `filter_criteria` AgentListFilter: Filters for listing agents. All provided filters are connected with AND.
    - `channel` object: Filter by agent channel. Use `op: eq`.
      - `type` 'string', required
      - `op` 'eq', required: eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains
      - `value` 'voice' | 'chat', required
    - `query` string: Case-insensitive substring search over agent name, plus substring search over agent id.
    - `is_transfer_agent` BooleanFilter
      - `type` 'boolean', required
      - `op` 'eq', required
      - `value` boolean, required

## Response `200`

Successfully retrieved agents.

- object
  - `pagination_key` string: Pagination key for the next page.
  - `has_more` boolean, required: Whether more results are available.
  - `items` AgentListItemResponse[], required
    - `agent_id` string, required: Unique id of agent.
    - `is_suspended` boolean, required: Whether the agent is currently suspended.
    - `agent_name` string, required: The name of the agent. Only used for your own reference.
    - `channel` 'voice' | 'chat', required
    - `user_modified_timestamp` integer, required: User modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.
    - `tags` object, required: Authoritative root tags for this agent, keyed by tag name.
    - `is_transfer_agent` boolean: Whether the agent is a transfer agent used for agentic warm transfer.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-10-22** `ee0f137f5417`: 1 info
  - added the required property `allOf[subschema #2]/items/items/is_suspended` to the response with the `200` status
- **2026-10-16** `ca41f0dbb297`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/retellai/apis/retell-sdk/changes/v2/list-agents/post.md)

---

[API](https://skmtc.dev/retellai/apis/retell-sdk.md) - [All operations](https://skmtc.dev/retellai/apis/retell-sdk/llms.txt) - [OpenAPI document](https://skmtc.dev/retellai/apis/retell-sdk/revisions/e482acaa292c?raw)