List Voice Agents

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const agents = await client.agent.list({
  filter_criteria: {
    channel: {
      op: 'eq',
      value: 'voice',
    },
  },
});

console.log(agents.items);

from retell import Retell

client = Retell(api_key="YOUR_RETELL_API_KEY")

agents = client.agent.list(
    filter_criteria={
        "channel": {
            "op": "eq",
            "value": "voice",
        },
    },
)

print(agents.items)

curl --request POST \
  --url 'https://api.retellai.com/v2/list-agents?limit=50' \
  --header 'Authorization: Bearer YOUR_RETELL_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter_criteria": {
      "channel": {
        "op": "eq",
        "value": "voice"
      }
    }
  }'

{
  "pagination_key": "<string>",
  "has_more": true,
  "items": [
    {
      "agent_id": "agent_1ffdb9717444d0e77346838911",
      "agent_name": "Jarvis",
      "channel": "voice",
      "user_modified_timestamp": 1703413636133,
      "tags": {}
    }
  ]
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

POST

list-agents

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const agents = await client.agent.list({
  filter_criteria: {
    channel: {
      op: 'eq',
      value: 'voice',
    },
  },
});

console.log(agents.items);

from retell import Retell

client = Retell(api_key="YOUR_RETELL_API_KEY")

agents = client.agent.list(
    filter_criteria={
        "channel": {
            "op": "eq",
            "value": "voice",
        },
    },
)

print(agents.items)

curl --request POST \
  --url 'https://api.retellai.com/v2/list-agents?limit=50' \
  --header 'Authorization: Bearer YOUR_RETELL_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter_criteria": {
      "channel": {
        "op": "eq",
        "value": "voice"
      }
    }
  }'

{
  "pagination_key": "<string>",
  "has_more": true,
  "items": [
    {
      "agent_id": "agent_1ffdb9717444d0e77346838911",
      "agent_name": "Jarvis",
      "channel": "voice",
      "user_modified_timestamp": 1703413636133,
      "tags": {}
    }
  ]
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Use filter_criteria.channel with value: "voice" to list only voice agents. The response is paginated. Read agents from items, then pass the returned pagination_key on the next request while has_more is true.

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const agents = await client.agent.list({
  filter_criteria: {
    channel: {
      op: 'eq',
      value: 'voice',
    },
  },
});

console.log(agents.items);

from retell import Retell

client = Retell(api_key="YOUR_RETELL_API_KEY")

agents = client.agent.list(
    filter_criteria={
        "channel": {
            "op": "eq",
            "value": "voice",
        },
    },
)

print(agents.items)

curl --request POST \
  --url 'https://api.retellai.com/v2/list-agents?limit=50' \
  --header 'Authorization: Bearer YOUR_RETELL_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter_criteria": {
      "channel": {
        "op": "eq",
        "value": "voice"
      }
    }
  }'

Authorizations

Authorization

string

header

required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Query Parameters

limit

integer

default:50

Maximum number of items to return.

Required range: x <= 1000

sort_order

enum<string>

default:descending

Sort order for results.

Available options:

ascending,

descending

pagination_key

string

Pagination key for fetching the next page.

Body

application/json

filter_criteria

object

Filters for listing agents. All provided filters are connected with AND.

Show child attributes

Response

Successfully retrieved agents.

pagination_key

string

Pagination key for the next page.

has_more

boolean

Whether more results are available.

items

object[]

Show child attributes

Get Voice Agent

Update Voice Agent

⌘I

Call

Chat

Playground

Phone Number

Voice Agent

Chat Agent

Retell LLM Response Engine (for single / multi prompt agent)

Conversation Flow Response Engine (for conversation flow agent)

Conversation Flow Subflows

MCP Tool

Knowledge Base

Voice

Batch call

Test Case Definitions

Batch Tests

Test Runs

Account

Custom Telephony

Custom LLM

Authorizations

Query Parameters

Body

Response