Get AI Agent
curl --request GET \
--url https://api.example.com/v3/ai-agents/{agent_id}import requests
url = "https://api.example.com/v3/ai-agents/{agent_id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v3/ai-agents/{agent_id}', 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/{agent_id}",
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/{agent_id}"
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/{agent_id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v3/ai-agents/{agent_id}")
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": "Agent retrieved successfully",
"data": {
"ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
"agent_name": "Customer Support Agent",
"agent_status": "ACTIVE",
"language_code": "en-US",
"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."
},
"stt": {
"provider_id": "6a5c45808d2d94e9d0e255d3",
"provider": "deepgram",
"model_id": "af97a5f7-0f10-4eb3-a915-f7fe95a050f8",
"model": "nova-3-general"
},
"tts": {
"provider_id": "6a5c079f814b8ed08b15172b",
"provider": "elevenlabs",
"voice_id": "IKne3meq5aSn9XLyUdCD",
"voice_name": "Charlie",
"model_name": "eleven_flash_v2_5",
"voice_temperature": 1
},
"speech_speed": 0.9,
"vad_activation_threshold": 0.4,
"knowledge_base_id": "kb-123456",
"enable_user_interruptions": true,
"minimum_speech_duration_for_interruptions": 0.5,
"minimum_words_before_interruption": 2,
"interruption_mode": "vad",
"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,
"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,
"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"
}
],
"organization_id": "org_7f3a9c",
"agent_owner_id": "usr_12ab34",
"created_by_user_id": "usr_12ab34",
"created_at": "2026-10-15T09:30:12.481Z",
"modified_at": "2026-10-15T10:02:47.115Z",
"current_version": 2,
"operation_type": "GET"
}
}
AI Agents v3
Get AI Agent
Retrieve one agent by id, with every catalog reference resolved to names.
The shape depends on the agent type. A simple agent has root llm, stt and tts. A flow agent has the root llm with graph_data, filled from the flow-default model, and no root stt or tts. See the two 200 examples.
The v2 equivalent, GET /v2/ai-agents/{agent_id}, is deprecated and stops working on November 30, 2026. This is the v3 endpoint. Migrate from v2 to v3 before that date.
Status codes
| Code | When |
|---|---|
200 | The agent exists, is ACTIVE and is in your scope. |
400 | The API key resolves to neither a workspace nor an organization. |
403 | The agent exists but belongs to another organization or workspace. |
404 | No such agent, or the agent is INACTIVE or DELETED. |
Errors use the envelope too, so 403 and 404 carry a body:
{
"status": "error",
"message": "Agent not found with ID: 3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42"
}
To see agents that are not ACTIVE, use List AI Agents with agent_status.
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. List items behave differently; see List AI Agents.
The response message is Agent retrieved successfully and operation_type is GET.
data.llm includes the resolved model_provider, model_name and model_display_name. Update AI Agent rejects those three fields with 400. Do not send data.llm back unchanged: remove those fields, or send only the fields you change.
GET
/
v3
/
ai-agents
/
{agent_id}
Get AI Agent
curl --request GET \
--url https://api.example.com/v3/ai-agents/{agent_id}import requests
url = "https://api.example.com/v3/ai-agents/{agent_id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/v3/ai-agents/{agent_id}', 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/{agent_id}",
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/{agent_id}"
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/{agent_id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v3/ai-agents/{agent_id}")
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": "Agent retrieved successfully",
"data": {
"ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
"agent_name": "Customer Support Agent",
"agent_status": "ACTIVE",
"language_code": "en-US",
"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."
},
"stt": {
"provider_id": "6a5c45808d2d94e9d0e255d3",
"provider": "deepgram",
"model_id": "af97a5f7-0f10-4eb3-a915-f7fe95a050f8",
"model": "nova-3-general"
},
"tts": {
"provider_id": "6a5c079f814b8ed08b15172b",
"provider": "elevenlabs",
"voice_id": "IKne3meq5aSn9XLyUdCD",
"voice_name": "Charlie",
"model_name": "eleven_flash_v2_5",
"voice_temperature": 1
},
"speech_speed": 0.9,
"vad_activation_threshold": 0.4,
"knowledge_base_id": "kb-123456",
"enable_user_interruptions": true,
"minimum_speech_duration_for_interruptions": 0.5,
"minimum_words_before_interruption": 2,
"interruption_mode": "vad",
"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,
"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,
"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"
}
],
"organization_id": "org_7f3a9c",
"agent_owner_id": "usr_12ab34",
"created_by_user_id": "usr_12ab34",
"created_at": "2026-10-15T09:30:12.481Z",
"modified_at": "2026-10-15T10:02:47.115Z",
"current_version": 2,
"operation_type": "GET"
}
}
Path Parameters
Unique identifier of the AI agent (ai_agent_id).
Response
The agent
Standard v3 envelope. error_details is present only on failures; null fields are omitted.
Outcome of the request: success or error, in lowercase.
Available options:
success, error Human-readable message about the result.
The agent. 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