List AI Agents
curl --request GET \
--url https://api.example.com/v3/ai-agentsimport requests
url = "https://api.example.com/v3/ai-agents"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v3/ai-agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v3/ai-agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v3/ai-agents"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v3/ai-agents")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v3/ai-agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"status": "success",
"message": "Agents retrieved successfully",
"data": {
"items": [
{
"ai_agent_id": "5b1e9d7c-2f4a-4e6b-8c3d-1a2b3c4d5e6f",
"agent_name": "New Flow Agent",
"agent_status": "ACTIVE",
"language_code": "en-US",
"timezone": null,
"llm": {
"llm_id": "d6847c0b-179f-4910-b4f5-a1bee9807a57",
"llm_type": "flow",
"model_provider": "openai",
"model_name": "gpt-4o-mini",
"model_display_name": "GPT-4o mini",
"model_temperature": 0.7,
"max_tokens": 4096,
"graph_data": {
"entryNodeId": "node-start",
"nodes": [
{
"id": "node-start",
"type": "start",
"position": {
"x": 300,
"y": 50
},
"data": {
"label": "Start",
"userAwayTimeoutSec": 30,
"maxToolSteps": 3
}
},
{
"id": "conv",
"type": "conversation",
"position": {
"x": 300,
"y": 200
},
"data": {
"label": "Conversation",
"mode": "full",
"instructions": "You are a helpful assistant.",
"openingMessage": {
"type": "llm-generated",
"instructions": "Greet the user and ask how you can help."
},
"modelConfig": {
"stt": {
"source": "flow-default"
},
"llm": {
"source": "flow-default"
},
"tts": {
"source": "flow-default"
}
},
"allowEndCall": true
}
},
{
"id": "end",
"type": "end-call",
"position": {
"x": 300,
"y": 350
},
"data": {
"label": "End call",
"farewellMessage": {
"type": "none"
}
}
}
],
"edges": [
{
"id": "e1",
"source": "node-start",
"target": "conv",
"label": "Start",
"kind": "session-start",
"contextPassing": "full"
},
{
"id": "e2",
"source": "conv",
"target": "end",
"label": "End Call",
"kind": "conditional-edge",
"decisionType": "llm",
"promptCondition": "When the user wants to end the call",
"contextPassing": "full"
}
],
"variables": [],
"globalNodeIds": [],
"agentDefaults": {
"stt": {
"provider_id": "6a5c45808d2d94e9d0e255d3",
"model_id": "aec2493a-eba9-48d0-9e64-4aab4437f7f5",
"provider": "deepgram",
"model": "nova-3"
},
"llm": {
"llm_id": "d6847c0b-179f-4910-b4f5-a1bee9807a57",
"provider": "openai",
"model": "gpt-4o-mini"
},
"tts": {
"provider_id": "6a5c079f814b8ed08b15172b",
"voice_id": "cgSgspJ2msm6clMCkdW9",
"provider": "elevenlabs",
"voice": "cgSgspJ2msm6clMCkdW9",
"model": "eleven_flash_v2_5"
}
},
"language": "en"
}
},
"tts": null,
"stt": null,
"speech_speed": 0.8,
"vad_activation_threshold": 0.5,
"enable_user_interruptions": true,
"minimum_speech_duration_for_interruptions": 0.5,
"minimum_words_before_interruption": 2,
"interruption_mode": "vad",
"wait_time_before_detecting_end_of_speech": 0.2,
"max_endpointing_delay": 2,
"ambient_sound": "none",
"ambient_sound_volume": 1,
"webhook_url": null,
"end_call_after_silence_seconds": 10,
"max_call_duration_seconds": 1800,
"welcome_message": null,
"end_call_instruction": null,
"amd_voicemail_message": null,
"voicemail_detection_timeout_seconds": 90,
"agent_ended_call_delay_seconds": 2,
"welcome_message_delay_in_seconds": 2,
"dynamic_data_config": null,
"post_call_analysis": null,
"pronunciations": null,
"created_at": "2026-10-15T09:41:03.220Z",
"modified_at": "2026-10-15T09:41:03.220Z",
"created_by_user_id": "usr_12ab34",
"modified_by_user_id": "usr_12ab34",
"knowledge_base_id": null,
"organization_id": "org_7f3a9c",
"workspace_id": null,
"agent_owner_id": null,
"enable_amd": false,
"silence_reminder_enabled": false,
"silence_reminder_duration_seconds": 10,
"max_number_of_silence_reminders": 3,
"interval_between_silence_reminders_seconds": 10,
"enable_noise_cancellation": null,
"current_version": 1,
"current_version_name": null
},
{
"ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
"agent_name": "Customer Support Agent",
"agent_status": "ACTIVE",
"language_code": "en-US",
"timezone": null,
"llm": {
"llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
"llm_type": "simple",
"model_provider": "openai",
"model_name": "gpt-4o-mini",
"model_display_name": "GPT-4o mini",
"model_temperature": 0.1,
"max_tokens": 4096,
"system_prompt": "You are a helpful customer support assistant."
},
"tts": {
"provider_id": "6a5c079f814b8ed08b15172b",
"provider": "elevenlabs",
"voice_id": "IKne3meq5aSn9XLyUdCD",
"voice_name": "Charlie",
"model_name": "eleven_flash_v2_5",
"voice_temperature": 1
},
"stt": {
"provider_id": "6a5c45808d2d94e9d0e255d3",
"provider": "deepgram",
"model_id": "af97a5f7-0f10-4eb3-a915-f7fe95a050f8",
"model": "nova-3-general"
},
"speech_speed": 0.9,
"vad_activation_threshold": 0.4,
"enable_user_interruptions": true,
"minimum_speech_duration_for_interruptions": 0.5,
"minimum_words_before_interruption": 2,
"interruption_mode": "vad",
"wait_time_before_detecting_end_of_speech": null,
"max_endpointing_delay": null,
"ambient_sound": "office",
"ambient_sound_volume": 1,
"webhook_url": "https://api.example.com/webhooks/call-events",
"end_call_after_silence_seconds": 20,
"max_call_duration_seconds": 600,
"welcome_message": "Hello! Thanks for calling. How can I help you today?",
"end_call_instruction": "End the call politely once the issue is resolved.",
"amd_voicemail_message": "Sorry we missed you. Please call us back.",
"voicemail_detection_timeout_seconds": 5,
"agent_ended_call_delay_seconds": 1,
"welcome_message_delay_in_seconds": 0.5,
"dynamic_data_config": [
{
"name": "customer_data",
"url": "https://api.example.com/customer-data",
"method": "GET",
"timeout": 2000,
"cache": true,
"response_data": [
{
"name": "customer_name",
"data": "$.customer.name",
"context": "Customer's full name for personalization"
}
]
}
],
"post_call_analysis": [
{
"type": "string",
"name": "call_summary",
"description": "A brief summary of the call and key points.",
"examples": [
"Customer asked about billing; issue resolved."
]
}
],
"pronunciations": [
{
"id": "r1",
"term": "API",
"replacement": "ay pee eye"
}
],
"created_at": "2026-10-15T09:30:12.481Z",
"modified_at": "2026-10-15T10:02:47.115Z",
"created_by_user_id": "usr_12ab34",
"modified_by_user_id": "usr_12ab34",
"knowledge_base_id": "kb-123456",
"organization_id": "org_7f3a9c",
"workspace_id": null,
"agent_owner_id": "usr_12ab34",
"enable_amd": true,
"silence_reminder_enabled": true,
"silence_reminder_duration_seconds": 15,
"max_number_of_silence_reminders": 3,
"interval_between_silence_reminders_seconds": 10,
"enable_noise_cancellation": true,
"current_version": 2,
"current_version_name": null
}
],
"next_page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xNVQwOTozMDoxMi40ODFaIiwiX2lkIjoiLi4uIn0"
}
}AI Agents v3
List AI Agents
List the agents in your tenant scope, newest first by default, with cursor pagination.
The v2 equivalent, GET /v2/ai-agents/, is deprecated and stops working on November 30, 2026. This is the v3 endpoint. Migrate from v2 to v3 before that date.
Scope
The list is bounded by the tenant your API key resolves to: a workspace when the key is workspace-scoped, otherwise the organization. It is not filtered by who created each agent, so every member of a workspace sees the same list. A key that resolves to neither scope gets 400.
Pagination
- Request the first page with
page_size(1–100, default10). - If
data.next_page_tokenis present, pass it back aspage_tokenfor the next page. Keep every other filter unchanged between pages. - When
data.next_page_tokenis absent, you have reached the last page.
Filters
| Parameter | Notes |
|---|---|
agent_ids | Restrict to specific ids. Repeat the parameter or pass a comma-separated list. |
agent_status | ACTIVE, INACTIVE or DELETED. Defaults to ACTIVE. Deleted agents are listed under INACTIVE. |
agent_type | simple, agentic or flow. |
agent_name | Name filter, at most 255 characters. |
sort_direction | asc or desc on creation time. Case-insensitive. |
A page_size outside 1–100 or an unknown sort_direction returns 422.
Response envelope
Every v3 response uses the same envelope:
| Field | Meaning |
|---|---|
status | success or error. Always lowercase. |
message | A human-readable summary. |
data | The result. Absent on errors. |
error_details | A map from field path to message. Present only on some errors. |
Fields with no value are omitted rather than returned as null.
The agents are in data.items and the cursor is in data.next_page_token:
{
"status": "success",
"message": "Agents retrieved successfully",
"data": {
"items": [ { "ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42", "agent_name": "Customer Support Agent" } ],
"next_page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xNVQwOTozMDoxMi40ODFaIiwiX2lkIjoiLi4uIn0"
}
}
List items use the stored agent shape. Unlike Get AI Agent, they include every field, with explicit nulls. They also carry modified_by_user_id and no operation_type. Do not assume a field’s presence is the same on both endpoints.
GET
/
v3
/
ai-agents
List AI Agents
curl --request GET \
--url https://api.example.com/v3/ai-agentsimport requests
url = "https://api.example.com/v3/ai-agents"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v3/ai-agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v3/ai-agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v3/ai-agents"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/v3/ai-agents")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v3/ai-agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"status": "success",
"message": "Agents retrieved successfully",
"data": {
"items": [
{
"ai_agent_id": "5b1e9d7c-2f4a-4e6b-8c3d-1a2b3c4d5e6f",
"agent_name": "New Flow Agent",
"agent_status": "ACTIVE",
"language_code": "en-US",
"timezone": null,
"llm": {
"llm_id": "d6847c0b-179f-4910-b4f5-a1bee9807a57",
"llm_type": "flow",
"model_provider": "openai",
"model_name": "gpt-4o-mini",
"model_display_name": "GPT-4o mini",
"model_temperature": 0.7,
"max_tokens": 4096,
"graph_data": {
"entryNodeId": "node-start",
"nodes": [
{
"id": "node-start",
"type": "start",
"position": {
"x": 300,
"y": 50
},
"data": {
"label": "Start",
"userAwayTimeoutSec": 30,
"maxToolSteps": 3
}
},
{
"id": "conv",
"type": "conversation",
"position": {
"x": 300,
"y": 200
},
"data": {
"label": "Conversation",
"mode": "full",
"instructions": "You are a helpful assistant.",
"openingMessage": {
"type": "llm-generated",
"instructions": "Greet the user and ask how you can help."
},
"modelConfig": {
"stt": {
"source": "flow-default"
},
"llm": {
"source": "flow-default"
},
"tts": {
"source": "flow-default"
}
},
"allowEndCall": true
}
},
{
"id": "end",
"type": "end-call",
"position": {
"x": 300,
"y": 350
},
"data": {
"label": "End call",
"farewellMessage": {
"type": "none"
}
}
}
],
"edges": [
{
"id": "e1",
"source": "node-start",
"target": "conv",
"label": "Start",
"kind": "session-start",
"contextPassing": "full"
},
{
"id": "e2",
"source": "conv",
"target": "end",
"label": "End Call",
"kind": "conditional-edge",
"decisionType": "llm",
"promptCondition": "When the user wants to end the call",
"contextPassing": "full"
}
],
"variables": [],
"globalNodeIds": [],
"agentDefaults": {
"stt": {
"provider_id": "6a5c45808d2d94e9d0e255d3",
"model_id": "aec2493a-eba9-48d0-9e64-4aab4437f7f5",
"provider": "deepgram",
"model": "nova-3"
},
"llm": {
"llm_id": "d6847c0b-179f-4910-b4f5-a1bee9807a57",
"provider": "openai",
"model": "gpt-4o-mini"
},
"tts": {
"provider_id": "6a5c079f814b8ed08b15172b",
"voice_id": "cgSgspJ2msm6clMCkdW9",
"provider": "elevenlabs",
"voice": "cgSgspJ2msm6clMCkdW9",
"model": "eleven_flash_v2_5"
}
},
"language": "en"
}
},
"tts": null,
"stt": null,
"speech_speed": 0.8,
"vad_activation_threshold": 0.5,
"enable_user_interruptions": true,
"minimum_speech_duration_for_interruptions": 0.5,
"minimum_words_before_interruption": 2,
"interruption_mode": "vad",
"wait_time_before_detecting_end_of_speech": 0.2,
"max_endpointing_delay": 2,
"ambient_sound": "none",
"ambient_sound_volume": 1,
"webhook_url": null,
"end_call_after_silence_seconds": 10,
"max_call_duration_seconds": 1800,
"welcome_message": null,
"end_call_instruction": null,
"amd_voicemail_message": null,
"voicemail_detection_timeout_seconds": 90,
"agent_ended_call_delay_seconds": 2,
"welcome_message_delay_in_seconds": 2,
"dynamic_data_config": null,
"post_call_analysis": null,
"pronunciations": null,
"created_at": "2026-10-15T09:41:03.220Z",
"modified_at": "2026-10-15T09:41:03.220Z",
"created_by_user_id": "usr_12ab34",
"modified_by_user_id": "usr_12ab34",
"knowledge_base_id": null,
"organization_id": "org_7f3a9c",
"workspace_id": null,
"agent_owner_id": null,
"enable_amd": false,
"silence_reminder_enabled": false,
"silence_reminder_duration_seconds": 10,
"max_number_of_silence_reminders": 3,
"interval_between_silence_reminders_seconds": 10,
"enable_noise_cancellation": null,
"current_version": 1,
"current_version_name": null
},
{
"ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
"agent_name": "Customer Support Agent",
"agent_status": "ACTIVE",
"language_code": "en-US",
"timezone": null,
"llm": {
"llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
"llm_type": "simple",
"model_provider": "openai",
"model_name": "gpt-4o-mini",
"model_display_name": "GPT-4o mini",
"model_temperature": 0.1,
"max_tokens": 4096,
"system_prompt": "You are a helpful customer support assistant."
},
"tts": {
"provider_id": "6a5c079f814b8ed08b15172b",
"provider": "elevenlabs",
"voice_id": "IKne3meq5aSn9XLyUdCD",
"voice_name": "Charlie",
"model_name": "eleven_flash_v2_5",
"voice_temperature": 1
},
"stt": {
"provider_id": "6a5c45808d2d94e9d0e255d3",
"provider": "deepgram",
"model_id": "af97a5f7-0f10-4eb3-a915-f7fe95a050f8",
"model": "nova-3-general"
},
"speech_speed": 0.9,
"vad_activation_threshold": 0.4,
"enable_user_interruptions": true,
"minimum_speech_duration_for_interruptions": 0.5,
"minimum_words_before_interruption": 2,
"interruption_mode": "vad",
"wait_time_before_detecting_end_of_speech": null,
"max_endpointing_delay": null,
"ambient_sound": "office",
"ambient_sound_volume": 1,
"webhook_url": "https://api.example.com/webhooks/call-events",
"end_call_after_silence_seconds": 20,
"max_call_duration_seconds": 600,
"welcome_message": "Hello! Thanks for calling. How can I help you today?",
"end_call_instruction": "End the call politely once the issue is resolved.",
"amd_voicemail_message": "Sorry we missed you. Please call us back.",
"voicemail_detection_timeout_seconds": 5,
"agent_ended_call_delay_seconds": 1,
"welcome_message_delay_in_seconds": 0.5,
"dynamic_data_config": [
{
"name": "customer_data",
"url": "https://api.example.com/customer-data",
"method": "GET",
"timeout": 2000,
"cache": true,
"response_data": [
{
"name": "customer_name",
"data": "$.customer.name",
"context": "Customer's full name for personalization"
}
]
}
],
"post_call_analysis": [
{
"type": "string",
"name": "call_summary",
"description": "A brief summary of the call and key points.",
"examples": [
"Customer asked about billing; issue resolved."
]
}
],
"pronunciations": [
{
"id": "r1",
"term": "API",
"replacement": "ay pee eye"
}
],
"created_at": "2026-10-15T09:30:12.481Z",
"modified_at": "2026-10-15T10:02:47.115Z",
"created_by_user_id": "usr_12ab34",
"modified_by_user_id": "usr_12ab34",
"knowledge_base_id": "kb-123456",
"organization_id": "org_7f3a9c",
"workspace_id": null,
"agent_owner_id": "usr_12ab34",
"enable_amd": true,
"silence_reminder_enabled": true,
"silence_reminder_duration_seconds": 15,
"max_number_of_silence_reminders": 3,
"interval_between_silence_reminders_seconds": 10,
"enable_noise_cancellation": true,
"current_version": 2,
"current_version_name": null
}
],
"next_page_token": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xNVQwOTozMDoxMi40ODFaIiwiX2lkIjoiLi4uIn0"
}
}Query Parameters
Number of agents per page, 1–100. Any other value returns 422.
Required range:
1 <= x <= 100Opaque cursor from the previous response's next_page_token. Omit for the first page.
Restrict the result to these agent ids. Repeat the parameter or pass a comma-separated list.
Filter by lifecycle status. Defaults to ACTIVE.
Available options:
ACTIVE, INACTIVE, DELETED Filter by LLM type of the agent.
Available options:
simple, agentic, flow Filter by agent name. Maximum 255 characters.
Maximum string length:
255Sort order on creation time. Case-insensitive; any other value returns 422.
Available options:
asc, desc Response
Page of agents
Standard v3 envelope wrapping a page. The envelope's data holds the page object; the agents are in its items array.
Outcome of the request: success or error, in lowercase.
Available options:
success, error Human-readable message about the result.
One page of agents. Omitted on errors.
Show child attributes
Show child attributes
Field path to message, for validation failures. Omitted when there are none.
Show child attributes
Show child attributes