Docs
Open Lodol
DocumentationIntegrationsAPI

Retell AI

App · Voice AI · 42 actions

Place, text and chat through Retell AI agents, read every call's transcript and analysis, and manage the voice agents, Retell LLMs, knowledge bases and phone numbers behind them.

Actions

ActionWhat it does
Add knowledge base sourcesAdd texts, web pages or files to a Retell AI knowledge base.
Buy phone numberBuy a new US or Canadian phone number from Retell AI, billed monthly to your Retell account, and choose the agents that use it.
Create batch callHave a Retell AI voice agent call a list of numbers, now or at a set time, only within the calling hours you choose.
Create chat agentCreate a Retell AI chat agent, which answers API chats and SMS, from an existing Response Engine such as a Retell LLM.
Create knowledge baseCreate a Retell AI knowledge base from texts, web pages and files, for agents to look answers up in.
Create phone callHave a Retell AI voice agent call a phone number.
Create Retell LLMCreate a Retell LLM: the prompt, model and opening line an agent answers with.
Create voice agentCreate a Retell AI voice agent from a voice and an existing Response Engine.
Create voice agent draftStart a new draft of a Retell AI voice agent, copied from one of its versions, so you can change it while the published version keeps taking calls.
Create web callStart a Retell AI call that someone joins from a web page, and get the access token your page connects with.
Delete callDelete a Retell AI call and everything Retell stored about it: its transcript, recording and analysis.
Delete chat agentDelete a Retell AI chat agent and all its versions.
Delete knowledge baseDelete a Retell AI knowledge base and everything in it.
Delete knowledge base sourceRemove one text, web page or file from a Retell AI knowledge base.
Delete Retell LLMDelete a Retell LLM and all its versions.
Delete voice agentDelete a Retell AI voice agent and all its versions.
End callHang up a Retell AI call that is in progress.
End chatEnd a Retell AI chat.
Get callFetch a Retell AI call: its status, transcript, recording, cost and Retell's analysis, such as its summary and whether it succeeded.
Get chatFetch a Retell AI chat or SMS conversation: its status, transcript, cost and Retell's analysis once it has ended.
Get concurrencySee how many Retell AI calls are running now and how many the account may run at once, for example before starting a batch.
Get knowledge baseFetch a Retell AI knowledge base, its sources, and whether Retell has finished reading them.
Get phone numberFetch one of your Retell AI phone numbers and the agents it uses.
Get Retell LLMFetch a Retell LLM: its prompt, model, tools and knowledge bases.
Get voiceFetch one Retell AI voice, with a link to a sample of it.
Get voice agentFetch one Retell AI voice agent's configuration: its voice, language, Response Engine, and version.
List callsList Retell AI calls, newest first, optionally only one agent's, only some statuses or directions, one number's, one batch's, or those that started in a time range.
List chat agentsList the chat agents on your Retell AI account, most recently modified first.
List chatsList Retell AI chats and SMS conversations, newest first, optionally only one agent's, only some statuses or types, or those that started in a time range.
List knowledge basesList every knowledge base on your Retell AI account.
List phone numbersList the phone numbers on your Retell AI account and the agents that answer, place calls and text from each.
List Retell LLMsList the Retell LLMs on your account, most recently modified first.
List voice agentsList the voice agents on your Retell AI account, most recently modified first.
List voicesList the voices a Retell AI agent can speak with, each with a link to a sample, optionally only one provider's, gender or accent.
Publish voice agentPublish a Retell AI voice agent's draft, which fixes it as a version phone numbers and environment tags can point at.
Send chat messageSend a message in a Retell AI chat and get the agent's answer.
Send SMSHave a Retell AI chat agent text a phone number.
Start chatOpen a text conversation with a Retell AI chat agent.
Update callChange an ended Retell AI call's metadata, how much of it Retell keeps, or its custom attributes.
Update phone numberChoose which Retell AI agents answer calls to a number, place calls from it, and handle its texts, or rename it.
Update Retell LLMChange a Retell LLM's prompt, first message, model or knowledge bases, for example to brief an agent before a campaign.
Update voice agentChange a Retell AI voice agent's voice, name, language, speech rate, webhook or Response Engine.

Add knowledge base sources

Add texts, web pages or files to a Retell AI knowledge base. Retell reads them in the background.

Inputs

Knowledge baseknowledge_base_idtextRequired
The knowledge base to act on. Pick one, or paste its ID.
Textstextslist
Optional. Texts to add, each an object with a title and the text. Plain text is added too, titled by its first line.
Web pagesurlslist
Optional. Addresses of pages for Retell to read and add, each starting with https://.
Filesfileslist
Optional. Documents to add, up to 25 at once and 50 MB each. Upload them, or use files from an earlier step.

Outputs

enable_auto_refreshtrue/false
Whether Retell re-reads its pages and connected files daily
knowledge_base_idtext
Knowledge base ID. Add it to a Retell LLM to let an agent use it.
knowledge_base_nametext
The knowledge base's name
knowledge_base_sourceslist
Its texts, pages and files, listed once indexing is complete
knowledge_base_statustext
in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
last_refreshed_timetext
When it was last refreshed, as ISO 8601
last_refreshed_timestampnumber
When it was last refreshed, in epoch milliseconds
max_chunk_sizenumber
Most characters per chunk
min_chunk_sizenumber
Fewest characters per chunk
Example output
{
  "enable_auto_refresh": true,
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Clinic FAQ",
  "knowledge_base_sources": [
    {
      "filename": "",
      "source_id": "source_7f3a9c",
      "title": "",
      "type": "url",
      "url": "https://www.example.com/faq"
    }
  ],
  "knowledge_base_status": "complete",
  "last_refreshed_time": "2026-07-21T15:00:07Z",
  "last_refreshed_timestamp": 1784646007000,
  "max_chunk_size": 2000,
  "min_chunk_size": 400
}

Buy phone number

Buy a new US or Canadian phone number from Retell AI, billed monthly to your Retell account, and choose the agents that use it.

Inputs

Area codearea_codenumber
Optional. The three-digit area code you'd like, such as 415.From 200 to 999.
Exact numberphone_numbertext
Optional. A specific available number to buy, in international format.
Countrycountry_codetext
Optional. Where the number is from. Defaults to the United States.One of: US (United States), CA (Canada).
Toll-freetoll_freetrue/false
Optional. Buy a toll-free number, which costs more.
Carriernumber_providertext
Optional. Who supplies the number. Defaults to Twilio.One of: twilio, telnyx.
Nicknamenicknametext
Optional. A name for the number, for your own reference.
Answers callsinbound_agent_idtext
Optional. The voice agent that answers calls to the number.
Places callsoutbound_agent_idtext
Optional. The voice agent that makes calls from the number.
Inbound webhook URLinbound_webhook_urltext
Optional. An address Retell asks before answering each inbound call, which can choose the agent, set dynamic variables or turn the call away.

Outputs

area_codenumber
The number's area code
inbound_agentslist
The agents that answer calls to it
inbound_sms_agentslist
The chat agents that answer texts to it
inbound_webhook_urltext
Where Retell asks how to handle each inbound call, if set
last_modification_timestampnumber
When it was last changed, in epoch milliseconds
last_modified_timetext
When it was last changed, as ISO 8601
nicknametext
The name you gave the number
outbound_agentslist
The agents that place calls from it
outbound_sms_agentslist
The chat agents that send texts from it
phone_numbertext
The number in E.164 form, such as +14157774444. It is its ID.
phone_number_prettytext
The number formatted for reading
phone_number_typetext
retell-twilio, retell-telnyx or custom
Example output
{
  "area_code": 415,
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "prod",
      "weight": 1
    }
  ],
  "inbound_sms_agents": [],
  "inbound_webhook_url": null,
  "last_modification_timestamp": 1784646007000,
  "last_modified_time": "2026-07-21T15:00:07Z",
  "nickname": "Front desk",
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "prod",
      "weight": 1
    }
  ],
  "outbound_sms_agents": [],
  "phone_number": "+14157774444",
  "phone_number_pretty": "+1 (415) 777-4444",
  "phone_number_type": "retell-twilio"
}

Create batch call

Have a Retell AI voice agent call a list of numbers, now or at a set time, only within the calling hours you choose. Each recipient can carry its own dynamic variables.

Inputs

From numberfrom_numbertextRequired
One of your Retell numbers to call from. Pick one, or type it in international format, such as +14157774444.
RecipientsrecipientslistRequired
Who to call. Each entry is a phone number, or an object with a to_number; its other keys become that call's dynamic variables, so a spreadsheet row with a phone column and a name column works as it is.
Voice agentagent_idtext
Optional. The agent that makes this call. Leave blank to use the agent the From number is set up with.
Batch namenametext
Optional. A name for your own reference.
Start atstart_atdate and time
Optional. When to start calling. Leave blank to start now.
Call fromwindow_starttime
Optional. The earliest time of day to call, in the calling time zone. Leave blank for midnight.
Call untilwindow_endtime
Optional. The latest time of day to call, in the calling time zone. Leave blank for the end of the day.
Calling time zonewindow_timezonetext
Optional. The time zone the calling hours are in. Defaults to America/Los_Angeles.
Calling dayswindow_dayslist
Optional. The days calls may be placed. Leave blank for every day.One or more of: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday.
Lines kept freereserved_concurrencynumber
Optional. How many of the account's simultaneous calls to keep free for others, such as inbound calls.At least 0.

Outputs

batch_call_idtext
Batch call ID. List calls filters by it to find its calls.
call_time_windowobject
The hours calls may be placed in, if any were set
from_numbertext
The number the calls are placed from
nametext
The batch call's name
scheduled_timetext
When the calls start, as ISO 8601
scheduled_timestampnumber
When the calls start, in epoch milliseconds
total_task_countnumber
How many calls the batch places
Example output
{
  "batch_call_id": "batch_call_dbcc4b0a7a6b2c38a0e2a8",
  "call_time_window": {
    "timezone": "America/New_York",
    "windows": [
      {
        "end": 1020,
        "start": 540
      }
    ]
  },
  "from_number": "+14157774444",
  "name": "July renewals",
  "scheduled_time": "2026-07-22T16:00:00Z",
  "scheduled_timestamp": 1784736000000,
  "total_task_count": 2
}

Create chat agent

Create a Retell AI chat agent, which answers API chats and SMS, from an existing Response Engine such as a Retell LLM.

Inputs

Response Engine typeresponse_engine_typetext
What kind of Response Engine drives the agent's replies. Defaults to retell-llm.One of: retell-llm (Retell LLM), conversation-flow (Conversation flow), custom-llm (Custom LLM). Default: retell-llm.
Response Engine IDresponse_engine_idtextRequired
ID of the Response Engine you already created, matching the type: a Retell LLM ID such as llm_234sdertfsdsfsdf (Create Retell LLM makes one), a conversation flow ID, or your custom LLM's websocket URL such as wss://example.com/llm. Not the type name.
Agent nameagent_nametext
Optional. A name for your own reference, for example 'Appointment reminders'.
Languagelanguagetext
Optional. The locale the agent speaks and listens in, which also tunes speech recognition. Defaults to en-US. For an agent that switches languages, list each one, separated by commas, such as en-US, es-ES; the voice must speak them all.Default: en-US.
Webhook URLwebhook_urltext
Optional. Where Retell sends this agent's chat events. Leave blank to use the account's webhook.

Outputs

agent_idtext
Chat agent ID. Use with Start chat or Send SMS.
agent_nametext
Name of the agent, blank if it was created without one
is_publishedtrue/false
Whether this version of the agent is published
languagetext
Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
last_modified_timetext
When the agent was last changed, as an ISO 8601 timestamp
response_engine_idtext
The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
response_engine_typetext
retell-llm, conversation-flow, or custom-llm
versionnumber
Version of the agent this record describes
webhook_urltext
Agent-level webhook for chat events, blank when the account webhook applies
Example output
{
  "agent_id": "agent_3f8b2a1c9d7e6f5a4b3c2d1e",
  "agent_name": "Booking assistant",
  "is_published": false,
  "language": "en-US",
  "last_modified_time": "2026-07-21T15:00:07Z",
  "response_engine_id": "llm_234sdertfsdsfsdf",
  "response_engine_type": "retell-llm",
  "version": 0,
  "webhook_url": ""
}

Create knowledge base

Create a Retell AI knowledge base from texts, web pages and files, for agents to look answers up in. Retell reads the sources in the background; Get knowledge base shows when it's done.

Inputs

NamenametextRequired
A name for the knowledge base, up to 39 characters.
Textstextslist
Optional. Texts to add, each an object with a title and the text. Plain text is added too, titled by its first line.
Web pagesurlslist
Optional. Addresses of pages for Retell to read and add, each starting with https://.
Filesfileslist
Optional. Documents to add, up to 25 at once and 50 MB each. Upload them, or use files from an earlier step.
Refresh dailyenable_auto_refreshtrue/false
Optional. Have Retell re-read the web pages every day, so the knowledge base keeps up with them.

Outputs

enable_auto_refreshtrue/false
Whether Retell re-reads its pages and connected files daily
knowledge_base_idtext
Knowledge base ID. Add it to a Retell LLM to let an agent use it.
knowledge_base_nametext
The knowledge base's name
knowledge_base_sourceslist
Its texts, pages and files, listed once indexing is complete
knowledge_base_statustext
in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
last_refreshed_timetext
When it was last refreshed, as ISO 8601
last_refreshed_timestampnumber
When it was last refreshed, in epoch milliseconds
max_chunk_sizenumber
Most characters per chunk
min_chunk_sizenumber
Fewest characters per chunk
Example output
{
  "enable_auto_refresh": true,
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Clinic FAQ",
  "knowledge_base_sources": [],
  "knowledge_base_status": "in_progress",
  "last_refreshed_time": "2026-07-21T15:00:07Z",
  "last_refreshed_timestamp": 1784646007000,
  "max_chunk_size": 2000,
  "min_chunk_size": 400
}

Create phone call

Have a Retell AI voice agent call a phone number. The call starts straight away; read its transcript and analysis with Get call once it has ended. Calls are billed by Retell.

Inputs

From numberfrom_numbertextRequired
One of your Retell numbers to call from. Pick one, or type it in international format, such as +14157774444.
To numberto_numbertextRequired
The number to contact, in international format, such as +12137774445. A number bought from Retell can only reach US numbers.
Voice agentagent_idtext
Optional. The agent that makes this call. Leave blank to use the agent the From number is set up with.
Agent versionagent_versiontext
Optional. Which version of the agent to use: a version number, an environment tag such as prod, or latest_published. Leave blank for the version the agent or number normally uses.
Dynamic variablesdynamic_variablesobject
Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
Metadatametadataobject
Optional. Anything of your own to keep with the record, such as your customer ID. Retell stores it and hands it back; the agent never sees it.
Respect do-not-callhonor_do_not_calltrue/false
Optional. When on, Retell refuses to contact a number whose contact is marked do not call.

Outputs

agent_idtext
The agent that handled the call
agent_nametext
Name of that agent
agent_versionnumber
Version of the agent the call used
call_analysisobject
Retell's analysis of the call, ready shortly after it ends
call_costobject
What the call cost
call_idtext
Call ID. Use with Get call, Update call or Delete call.
call_statustext
registered, not_connected, ongoing, ended or error
call_typetext
phone_call or web_call
collected_dynamic_variablesobject
Dynamic variables the agent collected during the call
data_storage_settingtext
How much of the call Retell keeps
directiontext
inbound or outbound, for a phone call
disconnection_reasontext
Why the call ended, such as user_hangup or voicemail_reached
duration_msnumber
How long the call lasted, in milliseconds
end_timetext
When the call ended, as ISO 8601
end_timestampnumber
When the call ended, in epoch milliseconds
from_numbertext
The calling number, for a phone call
metadataobject
The metadata the call was given
public_log_urltext
Link to the call's debugging log
recording_urltext
Link to the call recording, once it has ended
retell_llm_dynamic_variablesobject
The dynamic variables the call was given. Key-value pairs of text.
start_timetext
When the call started, as ISO 8601
start_timestampnumber
When the call started, in epoch milliseconds
to_numbertext
The number called, for a phone call
transcripttext
The call's transcript, once it has ended
transcript_objectlist
The transcript, one entry per utterance
transfer_destinationtext
Where the call was transferred to, if it was
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "agent_version": 1,
  "call_analysis": {},
  "call_cost": {},
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "call_status": "registered",
  "call_type": "phone_call",
  "collected_dynamic_variables": {},
  "data_storage_setting": "everything",
  "direction": "outbound",
  "disconnection_reason": "",
  "duration_ms": null,
  "end_time": "",
  "end_timestamp": null,
  "from_number": "+14157774444",
  "metadata": {
    "customer_id": "cus_1042"
  },
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/public_log.txt",
  "recording_url": "",
  "retell_llm_dynamic_variables": {
    "customer_name": "Ann"
  },
  "start_time": "2026-07-21T15:00:07Z",
  "start_timestamp": 1784646007000,
  "to_number": "+12137774445",
  "transcript": "",
  "transcript_object": [],
  "transfer_destination": null
}

Create Retell LLM

Create a Retell LLM: the prompt, model and opening line an agent answers with. Use its ID as the Response Engine of a voice or chat agent.

Inputs

Promptgeneral_prompttext
The instructions the agent follows: who it is, what it is for, and what it must not do. Write {{name}} where a dynamic variable goes.
First messagebegin_messagetext
Optional. What the agent says first. Leave blank and the model writes its own opening.
Who speaks firststart_speakertext
Whether the agent opens the conversation or waits.One of: agent (The agent speaks first), user (The agent waits for the caller).
Modelmodeltext
Optional. The text model the agent thinks with. Free text, since Retell adds and retires models often. Leave blank for Retell's default.
Temperaturemodel_temperaturenumber
Optional. How much the model varies its wording, from 0.0 (always the same) to 1.0. Retell's default is 0, which suits tool calling best.From 0.0 to 1.0.
Knowledge basesknowledge_base_idslist
Optional. IDs of knowledge bases the agent may look things up in, as Create knowledge base or List knowledge bases returns them.
Default dynamic variablesdefault_dynamic_variablesobject
Optional. Values for the prompt's {{placeholders}}, used when a call or chat doesn't supply its own.

Outputs

begin_messagetext
What the agent says first, if set
default_dynamic_variablesobject
Values used for dynamic variables a call doesn't set. Key-value pairs of text.
general_prompttext
The instructions the agent follows
general_toolslist
The tools the agent may call
is_publishedtrue/false
Whether this version is published
knowledge_base_idslist
The knowledge bases the agent looks things up in
last_modification_timestampnumber
When it was last changed, in epoch milliseconds
last_modified_timetext
When it was last changed, as ISO 8601
llm_idtext
Retell LLM ID. Use it as the Response Engine ID of a voice or chat agent.
modeltext
The text model it runs on
model_temperaturenumber
How much the model varies its wording, 0 to 1
start_speakertext
agent or user: who speaks first
versionnumber
Version of the Retell LLM
Example output
{
  "begin_message": "Hi {{customer_name}}, this is Ava from Bright Dental.",
  "default_dynamic_variables": {
    "customer_name": "there"
  },
  "general_prompt": "You are Ava, a friendly receptionist for Bright Dental.",
  "general_tools": [
    {
      "description": "End the call when the customer is done.",
      "name": "end_call",
      "type": "end_call"
    }
  ],
  "is_published": false,
  "knowledge_base_ids": [
    "knowledge_base_a456426614174000"
  ],
  "last_modification_timestamp": 1784646007000,
  "last_modified_time": "2026-07-21T15:00:07Z",
  "llm_id": "llm_234sdertfsdsfsdf",
  "model": "gpt-5.6-terra",
  "model_temperature": 0,
  "start_speaker": "agent",
  "version": 0
}

Create voice agent

Create a Retell AI voice agent from a voice and an existing Response Engine. The Response Engine (a Retell LLM, a conversation flow, or your own custom LLM) must already exist.

Inputs

Voicevoice_idtextRequired
The voice the agent speaks with. Pick one, or paste its voice ID, such as retell-Cimo. List voices shows them all, with a sample of each.
Response Engine typeresponse_engine_typetext
What kind of Response Engine drives the agent's replies. Defaults to retell-llm.One of: retell-llm (Retell LLM), conversation-flow (Conversation flow), custom-llm (Custom LLM). Default: retell-llm.
Response Engine IDresponse_engine_idtextRequired
ID of the Response Engine you already created, matching the type: a Retell LLM ID such as llm_234sdertfsdsfsdf (Create Retell LLM makes one), a conversation flow ID, or your custom LLM's websocket URL such as wss://example.com/llm. Not the type name.
Agent nameagent_nametext
Optional. A name for your own reference, for example 'Appointment reminders'.
Languagelanguagetext
Optional. The locale the agent speaks and listens in, which also tunes speech recognition. Defaults to en-US. For an agent that switches languages, list each one, separated by commas, such as en-US, es-ES; the voice must speak them all.Default: en-US.
Speech ratevoice_speednumber
Optional. How fast the agent speaks, from 0.5 (slower) to 2.0 (faster). Leave blank to use Retell's default of 1.0.From 0.5 to 2.0.
Webhook URLwebhook_urltext
Optional. Where Retell sends this agent's events, such as call_ended and call_analyzed. Leave blank to use the account's webhook.

Outputs

agent_idtext
Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
agent_nametext
Name of the agent, blank if it was created without one
is_publishedtrue/false
Whether this version of the agent is published
languagetext
Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
last_modified_timetext
When the agent was last changed, as an ISO 8601 timestamp
response_engine_idtext
The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
response_engine_typetext
retell-llm, conversation-flow, or custom-llm
versionnumber
Version of the agent this record describes
voice_idtext
Voice the agent speaks with
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "is_published": false,
  "language": "en-US",
  "last_modified_time": "2026-07-21T15:00:07Z",
  "response_engine_id": "llm_234sdertfsdsfsdf",
  "response_engine_type": "retell-llm",
  "version": 0,
  "voice_id": "retell-Cimo"
}

Create voice agent draft

Start a new draft of a Retell AI voice agent, copied from one of its versions, so you can change it while the published version keeps taking calls.

Inputs

Voice agentagent_idtextRequired
The voice agent to act on. Pick one, or paste its agent ID.
Copy from versionbase_versionnumber
Optional. The version number to copy. Leave blank for the latest version.At least 0.

Outputs

agent_idtext
Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
agent_nametext
Name of the agent, blank if it was created without one
is_publishedtrue/false
Whether this version of the agent is published
languagetext
Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
last_modified_timetext
When the agent was last changed, as an ISO 8601 timestamp
response_engine_idtext
The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
response_engine_typetext
retell-llm, conversation-flow, or custom-llm
versionnumber
Version of the agent this record describes
voice_idtext
Voice the agent speaks with
voice_modeltext
Voice model behind the voice, blank when the provider's default applies
voice_speednumber
Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
webhook_urltext
Agent-level webhook for call events, blank when the account webhook applies
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "is_published": false,
  "language": "en-US",
  "last_modified_time": "2026-07-21T15:00:07Z",
  "response_engine_id": "llm_234sdertfsdsfsdf",
  "response_engine_type": "retell-llm",
  "version": 1,
  "voice_id": "retell-Cimo",
  "voice_model": "eleven_flash_v2_5",
  "voice_speed": 1,
  "webhook_url": "https://example.com/retell-events"
}

Create web call

Start a Retell AI call that someone joins from a web page, and get the access token your page connects with. Nobody is dialed, and the token expires if it isn't used.

Inputs

Voice agentagent_idtextRequired
The voice agent that takes the call.
Agent versionagent_versiontext
Optional. Which version of the agent to use: a version number, an environment tag such as prod, or latest_published. Leave blank for the version the agent or number normally uses.
Dynamic variablesdynamic_variablesobject
Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
Metadatametadataobject
Optional. Anything of your own to keep with the record, such as your customer ID. Retell stores it and hands it back; the agent never sees it.

Outputs

access_tokentext
Token a browser joins the call with. Pass it to your web page.
call_idtext
Call ID. Use with Get call once the call is over.
expires_atnumber
When the access token expires, in epoch milliseconds
expires_timetext
When the access token expires, as ISO 8601
ice_serverslist
ICE servers the browser configures before connecting
transporttext
The connection transport to select in the web client
Example output
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tIjoid2ViIn19.sig",
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "expires_at": 1784646607000,
  "expires_time": "2026-07-21T15:10:07Z",
  "ice_servers": [
    {
      "credential": "c2VjcmV0",
      "urls": "turn:turn.retellai.com:443",
      "username": "1784646607:web"
    }
  ],
  "transport": "gateway"
}

Delete call

Delete a Retell AI call and everything Retell stored about it: its transcript, recording and analysis. This can't be undone. A call still in progress can't be deleted, and nor can a web call nobody joined until Retell gives up on it, 5 minutes after it was created.

Inputs

Call IDcall_idtextRequired
The call's ID, as Create phone call or List calls returns it.

Outputs

call_idtext
The call's ID
deletedtrue/false
True once the call is deleted
Example output
{
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "deleted": true
}

Delete chat agent

Delete a Retell AI chat agent and all its versions. This can't be undone.

Inputs

Chat agentagent_idtextRequired
The chat agent to act on. Pick one, or paste its agent ID.

Outputs

agent_idtext
The agent's ID
deletedtrue/false
True once the agent is deleted
Example output
{
  "agent_id": "agent_3f8b2a1c9d7e6f5a4b3c2d1e",
  "deleted": true
}

Delete knowledge base

Delete a Retell AI knowledge base and everything in it. This can't be undone.

Inputs

Knowledge baseknowledge_base_idtextRequired
The knowledge base to act on. Pick one, or paste its ID.

Outputs

deletedtrue/false
True once the knowledge base is deleted
knowledge_base_idtext
The knowledge base's ID
Example output
{
  "deleted": true,
  "knowledge_base_id": "knowledge_base_a456426614174000"
}

Delete knowledge base source

Remove one text, web page or file from a Retell AI knowledge base.

Inputs

Knowledge baseknowledge_base_idtextRequired
The knowledge base to act on. Pick one, or paste its ID.
Source IDsource_idtextRequired
The source to remove, as Get knowledge base lists it under its sources.

Outputs

enable_auto_refreshtrue/false
Whether Retell re-reads its pages and connected files daily
knowledge_base_idtext
Knowledge base ID. Add it to a Retell LLM to let an agent use it.
knowledge_base_nametext
The knowledge base's name
knowledge_base_sourceslist
Its texts, pages and files, listed once indexing is complete
knowledge_base_statustext
in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
last_refreshed_timetext
When it was last refreshed, as ISO 8601
last_refreshed_timestampnumber
When it was last refreshed, in epoch milliseconds
max_chunk_sizenumber
Most characters per chunk
min_chunk_sizenumber
Fewest characters per chunk
Example output
{
  "enable_auto_refresh": true,
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Clinic FAQ",
  "knowledge_base_sources": [],
  "knowledge_base_status": "complete",
  "last_refreshed_time": "2026-07-21T15:00:07Z",
  "last_refreshed_timestamp": 1784646007000,
  "max_chunk_size": 2000,
  "min_chunk_size": 400
}

Delete Retell LLM

Delete a Retell LLM and all its versions. Retell refuses while an agent still uses it, unless you force it. This can't be undone.

Inputs

Retell LLMllm_idtextRequired
The Retell LLM to act on. Pick one, or paste its ID.
Delete even if in useforcetrue/false
Optional. Delete it even though agents use it, which leaves those agents without a Response Engine.

Outputs

deletedtrue/false
True once the Retell LLM is deleted
llm_idtext
The Retell LLM's ID
Example output
{
  "deleted": true,
  "llm_id": "llm_234sdertfsdsfsdf"
}

Delete voice agent

Delete a Retell AI voice agent and all its versions. Its past calls are kept. This can't be undone.

Inputs

Voice agentagent_idtextRequired
The voice agent to act on. Pick one, or paste its agent ID.

Outputs

agent_idtext
The agent's ID
deletedtrue/false
True once the agent is deleted
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "deleted": true
}

End call

Hang up a Retell AI call that is in progress.

Inputs

Call IDcall_idtextRequired
The call's ID, as Create phone call or List calls returns it.

Outputs

call_idtext
The call's ID
endedtrue/false
True once the call is ended
Example output
{
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "ended": true
}

End chat

End a Retell AI chat. Retell then analyzes it, and Get chat returns the analysis.

Inputs

Chat IDchat_idtextRequired
The chat's ID, as Start chat, Send SMS or List chats returns it.

Outputs

chat_idtext
The chat's ID
endedtrue/false
True once the chat is ended
Example output
{
  "chat_id": "chat_98c1a2f3b4d5e6",
  "ended": true
}

Get call

Fetch a Retell AI call: its status, transcript, recording, cost and Retell's analysis, such as its summary and whether it succeeded. The analysis arrives shortly after the call ends.

Inputs

Call IDcall_idtextRequired
The call's ID, as Create phone call or List calls returns it.

Outputs

agent_idtext
The agent that handled the call
agent_nametext
Name of that agent
agent_versionnumber
Version of the agent the call used
call_analysisobject
Retell's analysis of the call, ready shortly after it ends
call_costobject
What the call cost
call_idtext
Call ID. Use with Get call, Update call or Delete call.
call_statustext
registered, not_connected, ongoing, ended or error
call_typetext
phone_call or web_call
collected_dynamic_variablesobject
Dynamic variables the agent collected during the call
data_storage_settingtext
How much of the call Retell keeps
directiontext
inbound or outbound, for a phone call
disconnection_reasontext
Why the call ended, such as user_hangup or voicemail_reached
duration_msnumber
How long the call lasted, in milliseconds
end_timetext
When the call ended, as ISO 8601
end_timestampnumber
When the call ended, in epoch milliseconds
from_numbertext
The calling number, for a phone call
metadataobject
The metadata the call was given
public_log_urltext
Link to the call's debugging log
recording_urltext
Link to the call recording, once it has ended
retell_llm_dynamic_variablesobject
The dynamic variables the call was given. Key-value pairs of text.
start_timetext
When the call started, as ISO 8601
start_timestampnumber
When the call started, in epoch milliseconds
to_numbertext
The number called, for a phone call
transcripttext
The call's transcript, once it has ended
transcript_objectlist
The transcript, one entry per utterance
transfer_destinationtext
Where the call was transferred to, if it was
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "agent_version": 1,
  "call_analysis": {
    "call_successful": true,
    "call_summary": "The customer confirmed Tuesday's appointment.",
    "custom_analysis_data": {
      "confirmed": true
    },
    "in_voicemail": false,
    "user_sentiment": "Positive"
  },
  "call_cost": {
    "combined_cost": 18.9,
    "total_duration_seconds": 126
  },
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "call_status": "ended",
  "call_type": "phone_call",
  "collected_dynamic_variables": {},
  "data_storage_setting": "everything",
  "direction": "outbound",
  "disconnection_reason": "user_hangup",
  "duration_ms": 126000,
  "end_time": "2026-07-21T15:02:13Z",
  "end_timestamp": 1784646133000,
  "from_number": "+14157774444",
  "metadata": {
    "customer_id": "cus_1042"
  },
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/public_log.txt",
  "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/recording.wav",
  "retell_llm_dynamic_variables": {
    "customer_name": "Ann"
  },
  "start_time": "2026-07-21T15:00:07Z",
  "start_timestamp": 1784646007000,
  "to_number": "+12137774445",
  "transcript": "Agent: Hi, this is Ava calling about your appointment...",
  "transcript_object": [
    {
      "content": "Hi, this is Ava calling about your appointment.",
      "role": "agent"
    }
  ],
  "transfer_destination": null
}

Get chat

Fetch a Retell AI chat or SMS conversation: its status, transcript, cost and Retell's analysis once it has ended.

Inputs

Chat IDchat_idtextRequired
The chat's ID, as Start chat, Send SMS or List chats returns it.

Outputs

agent_idtext
The chat agent in the conversation
chat_analysisobject
Retell's analysis of the chat, ready once it has ended
chat_costobject
What the chat cost
chat_idtext
Chat ID. Use with Send chat message, Get chat or End chat.
chat_statustext
ongoing, ended or error
chat_typetext
api_chat or sms_chat
collected_dynamic_variablesobject
Dynamic variables the agent collected during the chat
end_timetext
When the chat ended, as ISO 8601
end_timestampnumber
When the chat ended, in epoch milliseconds
message_with_tool_callslist
The conversation, one entry per message or tool call
metadataobject
The metadata the chat was given
retell_llm_dynamic_variablesobject
The dynamic variables the chat was given. Key-value pairs of text.
start_timetext
When the chat started, as ISO 8601
start_timestampnumber
When the chat started, in epoch milliseconds
transcripttext
The conversation so far
versionnumber
Version of the chat agent
Example output
{
  "agent_id": "agent_3f8b2a1c9d7e6f5a4b3c2d1e",
  "chat_analysis": {
    "chat_successful": true,
    "chat_summary": "The customer asked to move their appointment.",
    "custom_analysis_data": {},
    "user_sentiment": "Neutral"
  },
  "chat_cost": {
    "combined_cost": 0.4
  },
  "chat_id": "chat_98c1a2f3b4d5e6",
  "chat_status": "ongoing",
  "chat_type": "api_chat",
  "collected_dynamic_variables": {},
  "end_time": "",
  "end_timestamp": null,
  "message_with_tool_calls": [
    {
      "content": "Tuesday at 3pm is free. Shall I book it?",
      "created_timestamp": 1784646010000,
      "message_id": "msg_7b1e2c",
      "role": "agent"
    }
  ],
  "metadata": {
    "customer_id": "cus_1042"
  },
  "retell_llm_dynamic_variables": {
    "customer_name": "Ann"
  },
  "start_time": "2026-07-21T15:00:07Z",
  "start_timestamp": 1784646007000,
  "transcript": "User: Can I move my appointment?\nAgent: Of course. When suits you?",
  "version": 0
}

Get concurrency

See how many Retell AI calls are running now and how many the account may run at once, for example before starting a batch.

Inputs

None.

Outputs

base_concurrencynumber
The free part of that limit
concurrency_burst_enabledtrue/false
Whether calls may go over the limit, at a surcharge
concurrency_burst_limitnumber
The ceiling while bursting, or 0 when it is off
concurrency_limitnumber
How many calls the account may run at once
concurrency_purchase_limitnumber
The most that may be bought
current_concurrencynumber
How many calls are running now
purchased_concurrencynumber
The bought part of that limit
remaining_purchase_limitnumber
How much more may still be bought
reserved_inbound_concurrencynumber
Places kept free for inbound calls
Example output
{
  "base_concurrency": 20,
  "concurrency_burst_enabled": false,
  "concurrency_burst_limit": 0,
  "concurrency_limit": 20,
  "concurrency_purchase_limit": 100,
  "current_concurrency": 3,
  "purchased_concurrency": 0,
  "remaining_purchase_limit": 100,
  "reserved_inbound_concurrency": 2
}

Get knowledge base

Fetch a Retell AI knowledge base, its sources, and whether Retell has finished reading them.

Inputs

Knowledge baseknowledge_base_idtextRequired
The knowledge base to act on. Pick one, or paste its ID.

Outputs

enable_auto_refreshtrue/false
Whether Retell re-reads its pages and connected files daily
knowledge_base_idtext
Knowledge base ID. Add it to a Retell LLM to let an agent use it.
knowledge_base_nametext
The knowledge base's name
knowledge_base_sourceslist
Its texts, pages and files, listed once indexing is complete
knowledge_base_statustext
in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
last_refreshed_timetext
When it was last refreshed, as ISO 8601
last_refreshed_timestampnumber
When it was last refreshed, in epoch milliseconds
max_chunk_sizenumber
Most characters per chunk
min_chunk_sizenumber
Fewest characters per chunk
Example output
{
  "enable_auto_refresh": true,
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Clinic FAQ",
  "knowledge_base_sources": [
    {
      "filename": "",
      "source_id": "source_7f3a9c",
      "title": "",
      "type": "url",
      "url": "https://www.example.com/faq"
    }
  ],
  "knowledge_base_status": "complete",
  "last_refreshed_time": "2026-07-21T15:00:07Z",
  "last_refreshed_timestamp": 1784646007000,
  "max_chunk_size": 2000,
  "min_chunk_size": 400
}

Get phone number

Fetch one of your Retell AI phone numbers and the agents it uses.

Inputs

Phone numberphone_numbertextRequired
One of your Retell numbers. Pick one, or type it in international format, such as +14157774444.

Outputs

area_codenumber
The number's area code
inbound_agentslist
The agents that answer calls to it
inbound_sms_agentslist
The chat agents that answer texts to it
inbound_webhook_urltext
Where Retell asks how to handle each inbound call, if set
last_modification_timestampnumber
When it was last changed, in epoch milliseconds
last_modified_timetext
When it was last changed, as ISO 8601
nicknametext
The name you gave the number
outbound_agentslist
The agents that place calls from it
outbound_sms_agentslist
The chat agents that send texts from it
phone_numbertext
The number in E.164 form, such as +14157774444. It is its ID.
phone_number_prettytext
The number formatted for reading
phone_number_typetext
retell-twilio, retell-telnyx or custom
Example output
{
  "area_code": 415,
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "prod",
      "weight": 1
    }
  ],
  "inbound_sms_agents": [],
  "inbound_webhook_url": null,
  "last_modification_timestamp": 1784646007000,
  "last_modified_time": "2026-07-21T15:00:07Z",
  "nickname": "Front desk",
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "prod",
      "weight": 1
    }
  ],
  "outbound_sms_agents": [],
  "phone_number": "+14157774444",
  "phone_number_pretty": "+1 (415) 777-4444",
  "phone_number_type": "retell-twilio"
}

Get Retell LLM

Fetch a Retell LLM: its prompt, model, tools and knowledge bases.

Inputs

Retell LLMllm_idtextRequired
The Retell LLM to act on. Pick one, or paste its ID.
Versionversionnumber
Optional. The version number to read. Leave blank for the latest.At least 0.

Outputs

begin_messagetext
What the agent says first, if set
default_dynamic_variablesobject
Values used for dynamic variables a call doesn't set. Key-value pairs of text.
general_prompttext
The instructions the agent follows
general_toolslist
The tools the agent may call
is_publishedtrue/false
Whether this version is published
knowledge_base_idslist
The knowledge bases the agent looks things up in
last_modification_timestampnumber
When it was last changed, in epoch milliseconds
last_modified_timetext
When it was last changed, as ISO 8601
llm_idtext
Retell LLM ID. Use it as the Response Engine ID of a voice or chat agent.
modeltext
The text model it runs on
model_temperaturenumber
How much the model varies its wording, 0 to 1
start_speakertext
agent or user: who speaks first
versionnumber
Version of the Retell LLM
Example output
{
  "begin_message": "Hi {{customer_name}}, this is Ava from Bright Dental.",
  "default_dynamic_variables": {
    "customer_name": "there"
  },
  "general_prompt": "You are Ava, a friendly receptionist for Bright Dental.",
  "general_tools": [
    {
      "description": "End the call when the customer is done.",
      "name": "end_call",
      "type": "end_call"
    }
  ],
  "is_published": false,
  "knowledge_base_ids": [
    "knowledge_base_a456426614174000"
  ],
  "last_modification_timestamp": 1784646007000,
  "last_modified_time": "2026-07-21T15:00:07Z",
  "llm_id": "llm_234sdertfsdsfsdf",
  "model": "gpt-5.6-terra",
  "model_temperature": 0,
  "start_speaker": "agent",
  "version": 0
}

Get voice

Fetch one Retell AI voice, with a link to a sample of it.

Inputs

Voicevoice_idtextRequired
The voice to fetch. Pick one, or paste its voice ID.

Outputs

accenttext
Its accent, such as American
agetext
How old it sounds, such as Young
gendertext
male or female
preview_audio_urltext
Link to a sample of it
providertext
Who supplies it, such as elevenlabs or cartesia
voice_idtext
Voice ID. Use it as the Voice of a voice agent.
voice_nametext
The voice's name
Example output
{
  "accent": "American",
  "age": "Young",
  "gender": "female",
  "preview_audio_url": "https://retell-utils-public.s3.us-west-2.amazonaws.com/cimo.mp3",
  "provider": "platform",
  "voice_id": "retell-Cimo",
  "voice_name": "Cimo"
}

Get voice agent

Fetch one Retell AI voice agent's configuration: its voice, language, Response Engine, and version.

Inputs

Agent IDagent_idtextRequired
The agent's ID, as returned by Create voice agent or List voice agents.
Versionversiontext
Optional. Which version to read: a version number, an environment tag such as prod, or latest_published. Leave blank for the newest version.

Outputs

agent_idtext
Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
agent_nametext
Name of the agent, blank if it was created without one
is_publishedtrue/false
Whether this version of the agent is published
languagetext
Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
last_modified_timetext
When the agent was last changed, as an ISO 8601 timestamp
response_engine_idtext
The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
response_engine_typetext
retell-llm, conversation-flow, or custom-llm
versionnumber
Version of the agent this record describes
voice_idtext
Voice the agent speaks with
voice_modeltext
Voice model behind the voice, blank when the provider's default applies
voice_speednumber
Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
webhook_urltext
Agent-level webhook for call events, blank when the account webhook applies
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "is_published": false,
  "language": "en-US",
  "last_modified_time": "2026-07-21T15:00:07Z",
  "response_engine_id": "llm_234sdertfsdsfsdf",
  "response_engine_type": "retell-llm",
  "version": 0,
  "voice_id": "retell-Cimo",
  "voice_model": "eleven_flash_v2_5",
  "voice_speed": 1,
  "webhook_url": "https://example.com/retell-events"
}

List calls

List Retell AI calls, newest first, optionally only one agent's, only some statuses or directions, one number's, one batch's, or those that started in a time range.

Inputs

Voice agentagent_idtext
Optional. Only this agent's calls.
Statuscall_statuslist
Optional. Only calls in these states.One or more of: not_connected (Not connected), ongoing (In progress), ended, error (Failed).
Directiondirectiontext
Optional. Only inbound or only outbound calls.One of: inbound, outbound.
Call typecall_typetext
Optional. Only phone calls or only web calls.One of: phone_call (Phone call), web_call (Web call).
From numberfrom_numbertext
Optional. Only calls from this number, in international format.
To numberto_numbertext
Optional. Only calls to this number, in international format.
Batch call IDbatch_call_idtext
Optional. Only the calls a batch call placed, by the ID Create batch call returns.
Started on or afterstarted_afterdate and time
Optional. Only those that started at or after this moment.
Started on or beforestarted_beforedate and time
Optional. Only those that started at or before this moment.
Maximum recordslimitnumber
The most records to return, from 1 to 1000. Defaults to 50.From 1 to 1000. Default: 50.
Ordersort_ordertext
Newest or oldest first, by start time. Defaults to newest first.One of: descending (Newest first), ascending (Oldest first). Default: descending.
Page cursorpagination_keytext
Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

Outputs

callslist
The calls on this page, newest first
has_moretrue/false
Whether another page is available
pagination_keytext
Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.
Example output
{
  "calls": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_name": "Appointment reminders",
      "agent_version": 1,
      "call_analysis": {
        "call_successful": true,
        "call_summary": "The customer confirmed Tuesday's appointment.",
        "custom_analysis_data": {
          "confirmed": true
        },
        "in_voicemail": false,
        "user_sentiment": "Positive"
      },
      "call_cost": {
        "combined_cost": 18.9,
        "total_duration_seconds": 126
      },
      "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "call_status": "ended",
      "call_type": "phone_call",
      "collected_dynamic_variables": {},
      "data_storage_setting": "everything",
      "direction": "outbound",
      "disconnection_reason": "user_hangup",
      "duration_ms": 126000,
      "end_time": "2026-07-21T15:02:13Z",
      "end_timestamp": 1784646133000,
      "from_number": "+14157774444",
      "metadata": {
        "customer_id": "cus_1042"
      },
      "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/public_log.txt",
      "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/recording.wav",
      "retell_llm_dynamic_variables": {
        "customer_name": "Ann"
      },
      "start_time": "2026-07-21T15:00:07Z",
      "start_timestamp": 1784646007000,
      "to_number": "+12137774445",
      "transcript": "Agent: Hi, this is Ava calling about your appointment...",
      "transcript_object": [
        {
          "content": "Hi, this is Ava calling about your appointment.",
          "role": "agent"
        }
      ],
      "transfer_destination": null
    }
  ],
  "has_more": true,
  "pagination_key": "call_8f2a91c4d3b7e6"
}

List chat agents

List the chat agents on your Retell AI account, most recently modified first. Voice agents are left out.

Inputs

Searchquerytext
Optional. Only include agents whose name or ID contains this text. Leave blank for every agent.
Maximum agentslimitnumber
The most agents to return, from 1 to 1000. Defaults to 50.From 1 to 1000. Default: 50.
Page cursorpagination_keytext
Optional. Pass the 'pagination_key' from a previous run to fetch the next page of agents.

Outputs

agentslist
Agents on this page, most recently modified first
has_moretrue/false
Whether another page is available
pagination_keytext
Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.
Example output
{
  "agents": [
    {
      "agent_id": "agent_3f8b2a1c9d7e6f5a4b3c2d1e",
      "agent_name": "Booking assistant",
      "last_modified_time": "2026-07-21T15:00:07Z"
    }
  ],
  "has_more": true,
  "pagination_key": "agent_1ffdb9717444d0e77346838911"
}

List chats

List Retell AI chats and SMS conversations, newest first, optionally only one agent's, only some statuses or types, or those that started in a time range.

Inputs

Chat agentagent_idtext
Optional. Only this agent's chats.
Statuschat_statuslist
Optional. Only chats in these states.One or more of: ongoing (In progress), ended, error (Failed).
Chat typechat_typetext
Optional. Only API chats or only SMS conversations.One of: api_chat (API chat), sms_chat (SMS).
Started on or afterstarted_afterdate and time
Optional. Only those that started at or after this moment.
Started on or beforestarted_beforedate and time
Optional. Only those that started at or before this moment.
Maximum recordslimitnumber
The most records to return, from 1 to 1000. Defaults to 50.From 1 to 1000. Default: 50.
Ordersort_ordertext
Newest or oldest first, by start time. Defaults to newest first.One of: descending (Newest first), ascending (Oldest first). Default: descending.
Page cursorpagination_keytext
Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

Outputs

chatslist
The chats on this page, newest first
has_moretrue/false
Whether another page is available
pagination_keytext
Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.
Example output
{
  "chats": [
    {
      "agent_id": "agent_3f8b2a1c9d7e6f5a4b3c2d1e",
      "chat_analysis": {
        "chat_successful": true,
        "chat_summary": "The customer asked to move their appointment.",
        "custom_analysis_data": {},
        "user_sentiment": "Neutral"
      },
      "chat_cost": {
        "combined_cost": 0.4
      },
      "chat_id": "chat_98c1a2f3b4d5e6",
      "chat_status": "ongoing",
      "chat_type": "api_chat",
      "collected_dynamic_variables": {},
      "end_time": "",
      "end_timestamp": null,
      "message_with_tool_calls": [
        {
          "content": "Tuesday at 3pm is free. Shall I book it?",
          "created_timestamp": 1784646010000,
          "message_id": "msg_7b1e2c",
          "role": "agent"
        }
      ],
      "metadata": {
        "customer_id": "cus_1042"
      },
      "retell_llm_dynamic_variables": {
        "customer_name": "Ann"
      },
      "start_time": "2026-07-21T15:00:07Z",
      "start_timestamp": 1784646007000,
      "transcript": "User: Can I move my appointment?\nAgent: Of course. When suits you?",
      "version": 0
    }
  ],
  "has_more": false,
  "pagination_key": "chat_3c7d1e9f2a"
}

List knowledge bases

List every knowledge base on your Retell AI account.

Inputs

None.

Outputs

countnumber
How many knowledge bases there are
knowledge_baseslist
Every knowledge base on the account
Example output
{
  "count": 1,
  "knowledge_bases": [
    {
      "enable_auto_refresh": true,
      "knowledge_base_id": "knowledge_base_a456426614174000",
      "knowledge_base_name": "Clinic FAQ",
      "knowledge_base_sources": [
        {
          "filename": "",
          "source_id": "source_7f3a9c",
          "title": "",
          "type": "url",
          "url": "https://www.example.com/faq"
        }
      ],
      "knowledge_base_status": "complete",
      "last_refreshed_time": "2026-07-21T15:00:07Z",
      "last_refreshed_timestamp": 1784646007000,
      "max_chunk_size": 2000,
      "min_chunk_size": 400
    }
  ]
}

List phone numbers

List the phone numbers on your Retell AI account and the agents that answer, place calls and text from each.

Inputs

Maximum recordslimitnumber
The most records to return, from 1 to 1000. Defaults to 50.From 1 to 1000. Default: 50.
Page cursorpagination_keytext
Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

Outputs

has_moretrue/false
Whether another page is available
pagination_keytext
Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.
phone_numberslist
The numbers on this page
Example output
{
  "has_more": false,
  "pagination_key": "",
  "phone_numbers": [
    {
      "area_code": 415,
      "inbound_agents": [
        {
          "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
          "agent_version": "prod",
          "weight": 1
        }
      ],
      "inbound_sms_agents": [],
      "inbound_webhook_url": null,
      "last_modification_timestamp": 1784646007000,
      "last_modified_time": "2026-07-21T15:00:07Z",
      "nickname": "Front desk",
      "outbound_agents": [
        {
          "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
          "agent_version": "prod",
          "weight": 1
        }
      ],
      "outbound_sms_agents": [],
      "phone_number": "+14157774444",
      "phone_number_pretty": "+1 (415) 777-4444",
      "phone_number_type": "retell-twilio"
    }
  ]
}

List Retell LLMs

List the Retell LLMs on your account, most recently modified first.

Inputs

Maximum recordslimitnumber
The most records to return, from 1 to 1000. Defaults to 50.From 1 to 1000. Default: 50.
Page cursorpagination_keytext
Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

Outputs

has_moretrue/false
Whether another page is available
llmslist
The Retell LLMs on this page
pagination_keytext
Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.
Example output
{
  "has_more": false,
  "llms": [
    {
      "begin_message": "Hi {{customer_name}}, this is Ava from Bright Dental.",
      "default_dynamic_variables": {
        "customer_name": "there"
      },
      "general_prompt": "You are Ava, a friendly receptionist for Bright Dental.",
      "general_tools": [
        {
          "description": "End the call when the customer is done.",
          "name": "end_call",
          "type": "end_call"
        }
      ],
      "is_published": false,
      "knowledge_base_ids": [
        "knowledge_base_a456426614174000"
      ],
      "last_modification_timestamp": 1784646007000,
      "last_modified_time": "2026-07-21T15:00:07Z",
      "llm_id": "llm_234sdertfsdsfsdf",
      "model": "gpt-5.6-terra",
      "model_temperature": 0,
      "start_speaker": "agent",
      "version": 0
    }
  ],
  "pagination_key": ""
}

List voice agents

List the voice agents on your Retell AI account, most recently modified first. Chat agents are left out.

Inputs

Searchquerytext
Optional. Only include agents whose name or ID contains this text. Leave blank for every agent.
Maximum agentslimitnumber
The most agents to return, from 1 to 1000. Defaults to 50.From 1 to 1000. Default: 50.
Page cursorpagination_keytext
Optional. Pass the 'pagination_key' from a previous run to fetch the next page of agents.

Outputs

agentslist
Agents on this page, most recently modified first
has_moretrue/false
Whether another page is available
pagination_keytext
Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.
Example output
{
  "agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_name": "Appointment reminders",
      "last_modified_time": "2026-07-21T15:00:07Z"
    }
  ],
  "has_more": true,
  "pagination_key": "agent_1ffdb9717444d0e77346838911"
}

List voices

List the voices a Retell AI agent can speak with, each with a link to a sample, optionally only one provider's, gender or accent.

Inputs

Providerprovidertext
Optional. Only this provider's voices.One of: elevenlabs, openai, cartesia, minimax, fish_audio (Fish Audio), inworld, platform (Retell).
Gendergendertext
Optional. Only female or only male voices.One of: female, male.
Accentaccenttext
Optional. Only voices whose accent contains this text, such as British.
Name containsname_containstext
Optional. Only voices whose name contains this text.

Outputs

countnumber
How many matched
voiceslist
The voices that matched
Example output
{
  "count": 1,
  "voices": [
    {
      "accent": "American",
      "age": "Young",
      "gender": "female",
      "preview_audio_url": "https://retell-utils-public.s3.us-west-2.amazonaws.com/cimo.mp3",
      "provider": "platform",
      "voice_id": "retell-Cimo",
      "voice_name": "Cimo"
    }
  ]
}

Publish voice agent

Publish a Retell AI voice agent's draft, which fixes it as a version phone numbers and environment tags can point at. Publishes the latest draft unless you name a version.

Inputs

Voice agentagent_idtextRequired
The voice agent to act on. Pick one, or paste its agent ID.
Versionversionnumber
Optional. The number of the draft to publish. Leave blank for the latest version; if that is already published, nothing changes.At least 0.
Version titleversion_titletext
Optional. A title for the version, for your own reference.
Version notesversion_descriptiontext
Optional. What changed in this version.

Outputs

agent_idtext
Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
agent_nametext
Name of the agent, blank if it was created without one
is_publishedtrue/false
Whether this version of the agent is published
languagetext
Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
last_modified_timetext
When the agent was last changed, as an ISO 8601 timestamp
response_engine_idtext
The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
response_engine_typetext
retell-llm, conversation-flow, or custom-llm
versionnumber
Version of the agent this record describes
voice_idtext
Voice the agent speaks with
voice_modeltext
Voice model behind the voice, blank when the provider's default applies
voice_speednumber
Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
webhook_urltext
Agent-level webhook for call events, blank when the account webhook applies
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "is_published": true,
  "language": "en-US",
  "last_modified_time": "2026-07-21T15:00:07Z",
  "response_engine_id": "llm_234sdertfsdsfsdf",
  "response_engine_type": "retell-llm",
  "version": 0,
  "voice_id": "retell-Cimo",
  "voice_model": "eleven_flash_v2_5",
  "voice_speed": 1,
  "webhook_url": "https://example.com/retell-events"
}

Send chat message

Send a message in a Retell AI chat and get the agent's answer.

Inputs

Chat IDchat_idtextRequired
The chat's ID, as Start chat, Send SMS or List chats returns it.
MessagemessagetextRequired
What the person says to the agent.

Outputs

chat_idtext
The chat's ID
messageslist
Everything the agent did in answer, tool calls included
replytext
The agent's answer: its messages, without the tool calls between them
Example output
{
  "chat_id": "chat_98c1a2f3b4d5e6",
  "messages": [
    {
      "content": "Tuesday at 3pm is free. Shall I book it?",
      "created_timestamp": 1784646010000,
      "message_id": "msg_7b1e2c",
      "role": "agent"
    }
  ],
  "reply": "Tuesday at 3pm is free. Shall I book it?"
}

Send SMS

Have a Retell AI chat agent text a phone number. The agent writes the first message from its prompt and answers replies. The From number must have SMS enabled in Retell.

Inputs

From numberfrom_numbertextRequired
One of your Retell numbers with SMS enabled. Pick one, or type it in international format.
To numberto_numbertextRequired
The number to text, in international format, such as +12137774445.
Chat agentagent_idtext
Optional. The chat agent that texts. Leave blank to use the agent the From number sends texts with.
Agent versionagent_versiontext
Optional. Which version of the agent to use: a version number, an environment tag such as prod, or latest_published. Leave blank for the version the agent or number normally uses.
Dynamic variablesdynamic_variablesobject
Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
Metadatametadataobject
Optional. Anything of your own to keep with the record, such as your customer ID. Retell stores it and hands it back; the agent never sees it.
Respect do-not-callhonor_do_not_calltrue/false
Optional. When on, Retell refuses to contact a number whose contact is marked do not call.

Outputs

agent_idtext
The chat agent in the conversation
chat_analysisobject
Retell's analysis of the chat, ready once it has ended
chat_costobject
What the chat cost
chat_idtext
Chat ID. Use with Send chat message, Get chat or End chat.
chat_statustext
ongoing, ended or error
chat_typetext
api_chat or sms_chat
collected_dynamic_variablesobject
Dynamic variables the agent collected during the chat
end_timetext
When the chat ended, as ISO 8601
end_timestampnumber
When the chat ended, in epoch milliseconds
message_with_tool_callslist
The conversation, one entry per message or tool call
metadataobject
The metadata the chat was given
retell_llm_dynamic_variablesobject
The dynamic variables the chat was given. Key-value pairs of text.
start_timetext
When the chat started, as ISO 8601
start_timestampnumber
When the chat started, in epoch milliseconds
transcripttext
The conversation so far
versionnumber
Version of the chat agent
Example output
{
  "agent_id": "agent_3f8b2a1c9d7e6f5a4b3c2d1e",
  "chat_analysis": {
    "chat_successful": true,
    "chat_summary": "The customer asked to move their appointment.",
    "custom_analysis_data": {},
    "user_sentiment": "Neutral"
  },
  "chat_cost": {
    "combined_cost": 0.4
  },
  "chat_id": "chat_98c1a2f3b4d5e6",
  "chat_status": "ongoing",
  "chat_type": "sms_chat",
  "collected_dynamic_variables": {},
  "end_time": "",
  "end_timestamp": null,
  "message_with_tool_calls": [
    {
      "content": "Tuesday at 3pm is free. Shall I book it?",
      "created_timestamp": 1784646010000,
      "message_id": "msg_7b1e2c",
      "role": "agent"
    }
  ],
  "metadata": {
    "customer_id": "cus_1042"
  },
  "retell_llm_dynamic_variables": {
    "customer_name": "Ann"
  },
  "start_time": "2026-07-21T15:00:07Z",
  "start_timestamp": 1784646007000,
  "transcript": "User: Can I move my appointment?\nAgent: Of course. When suits you?",
  "version": 0
}

Start chat

Open a text conversation with a Retell AI chat agent. Send it messages with Send chat message, and end it with End chat.

Inputs

Chat agentagent_idtextRequired
The chat agent to act on. Pick one, or paste its agent ID.
Agent versionagent_versiontext
Optional. Which version of the agent to use: a version number, an environment tag such as prod, or latest_published. Leave blank for the version the agent or number normally uses.
Dynamic variablesdynamic_variablesobject
Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
Metadatametadataobject
Optional. Anything of your own to keep with the record, such as your customer ID. Retell stores it and hands it back; the agent never sees it.

Outputs

agent_idtext
The chat agent in the conversation
chat_analysisobject
Retell's analysis of the chat, ready once it has ended
chat_costobject
What the chat cost
chat_idtext
Chat ID. Use with Send chat message, Get chat or End chat.
chat_statustext
ongoing, ended or error
chat_typetext
api_chat or sms_chat
collected_dynamic_variablesobject
Dynamic variables the agent collected during the chat
end_timetext
When the chat ended, as ISO 8601
end_timestampnumber
When the chat ended, in epoch milliseconds
message_with_tool_callslist
The conversation, one entry per message or tool call
metadataobject
The metadata the chat was given
retell_llm_dynamic_variablesobject
The dynamic variables the chat was given. Key-value pairs of text.
start_timetext
When the chat started, as ISO 8601
start_timestampnumber
When the chat started, in epoch milliseconds
transcripttext
The conversation so far
versionnumber
Version of the chat agent
Example output
{
  "agent_id": "agent_3f8b2a1c9d7e6f5a4b3c2d1e",
  "chat_analysis": {
    "chat_successful": true,
    "chat_summary": "The customer asked to move their appointment.",
    "custom_analysis_data": {},
    "user_sentiment": "Neutral"
  },
  "chat_cost": {
    "combined_cost": 0.4
  },
  "chat_id": "chat_98c1a2f3b4d5e6",
  "chat_status": "ongoing",
  "chat_type": "api_chat",
  "collected_dynamic_variables": {},
  "end_time": "",
  "end_timestamp": null,
  "message_with_tool_calls": [],
  "metadata": {
    "customer_id": "cus_1042"
  },
  "retell_llm_dynamic_variables": {
    "customer_name": "Ann"
  },
  "start_time": "2026-07-21T15:00:07Z",
  "start_timestamp": 1784646007000,
  "transcript": "",
  "version": 0
}

Update call

Change an ended Retell AI call's metadata, how much of it Retell keeps, or its custom attributes. Retell only updates calls that have ended.

Inputs

Call IDcall_idtextRequired
The call's ID, as Create phone call or List calls returns it.
Metadatametadataobject
Optional. New metadata for the call, replacing what it has. Up to 50 kB.
Data keptdata_storage_settingtext
Optional. How much of the call Retell keeps. It can only be made stricter, never looser.One of: everything, everything_except_pii (Everything except personal data), basic_attributes_only (Only basic details).
Custom attributescustom_attributesobject
Optional. Values for attributes set up under Call History > Actions > Custom attributes in the Retell dashboard, keyed by each attribute's ID.

Outputs

agent_idtext
The agent that handled the call
agent_nametext
Name of that agent
agent_versionnumber
Version of the agent the call used
call_analysisobject
Retell's analysis of the call, ready shortly after it ends
call_costobject
What the call cost
call_idtext
Call ID. Use with Get call, Update call or Delete call.
call_statustext
registered, not_connected, ongoing, ended or error
call_typetext
phone_call or web_call
collected_dynamic_variablesobject
Dynamic variables the agent collected during the call
data_storage_settingtext
How much of the call Retell keeps
directiontext
inbound or outbound, for a phone call
disconnection_reasontext
Why the call ended, such as user_hangup or voicemail_reached
duration_msnumber
How long the call lasted, in milliseconds
end_timetext
When the call ended, as ISO 8601
end_timestampnumber
When the call ended, in epoch milliseconds
from_numbertext
The calling number, for a phone call
metadataobject
The metadata the call was given
public_log_urltext
Link to the call's debugging log
recording_urltext
Link to the call recording, once it has ended
retell_llm_dynamic_variablesobject
The dynamic variables the call was given. Key-value pairs of text.
start_timetext
When the call started, as ISO 8601
start_timestampnumber
When the call started, in epoch milliseconds
to_numbertext
The number called, for a phone call
transcripttext
The call's transcript, once it has ended
transcript_objectlist
The transcript, one entry per utterance
transfer_destinationtext
Where the call was transferred to, if it was
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "agent_version": 1,
  "call_analysis": {
    "call_successful": true,
    "call_summary": "The customer confirmed Tuesday's appointment.",
    "custom_analysis_data": {
      "confirmed": true
    },
    "in_voicemail": false,
    "user_sentiment": "Positive"
  },
  "call_cost": {
    "combined_cost": 18.9,
    "total_duration_seconds": 126
  },
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "call_status": "ended",
  "call_type": "phone_call",
  "collected_dynamic_variables": {},
  "data_storage_setting": "everything",
  "direction": "outbound",
  "disconnection_reason": "user_hangup",
  "duration_ms": 126000,
  "end_time": "2026-07-21T15:02:13Z",
  "end_timestamp": 1784646133000,
  "from_number": "+14157774444",
  "metadata": {
    "customer_id": "cus_1042"
  },
  "public_log_url": "https://retellai.s3.us-west-2.amazonaws.com/public_log.txt",
  "recording_url": "https://retellai.s3.us-west-2.amazonaws.com/recording.wav",
  "retell_llm_dynamic_variables": {
    "customer_name": "Ann"
  },
  "start_time": "2026-07-21T15:00:07Z",
  "start_timestamp": 1784646007000,
  "to_number": "+12137774445",
  "transcript": "Agent: Hi, this is Ava calling about your appointment...",
  "transcript_object": [
    {
      "content": "Hi, this is Ava calling about your appointment.",
      "role": "agent"
    }
  ],
  "transfer_destination": null
}

Update phone number

Choose which Retell AI agents answer calls to a number, place calls from it, and handle its texts, or rename it. Only the fields you fill in change.

Inputs

Phone numberphone_numbertextRequired
One of your Retell numbers. Pick one, or type it in international format, such as +14157774444.
Answers callsinbound_agent_idtext
Optional. The voice agent that answers calls to the number.
Places callsoutbound_agent_idtext
Optional. The voice agent that makes calls from the number.
Answers textsinbound_sms_agent_idtext
Optional. The chat agent that answers texts to the number.
Sends textsoutbound_sms_agent_idtext
Optional. The chat agent that sends texts from the number.
Nicknamenicknametext
Optional. A name for the number, for your own reference.
Inbound webhook URLinbound_webhook_urltext
Optional. An address Retell asks before answering each inbound call, which can choose the agent, set dynamic variables or turn the call away.

Outputs

area_codenumber
The number's area code
inbound_agentslist
The agents that answer calls to it
inbound_sms_agentslist
The chat agents that answer texts to it
inbound_webhook_urltext
Where Retell asks how to handle each inbound call, if set
last_modification_timestampnumber
When it was last changed, in epoch milliseconds
last_modified_timetext
When it was last changed, as ISO 8601
nicknametext
The name you gave the number
outbound_agentslist
The agents that place calls from it
outbound_sms_agentslist
The chat agents that send texts from it
phone_numbertext
The number in E.164 form, such as +14157774444. It is its ID.
phone_number_prettytext
The number formatted for reading
phone_number_typetext
retell-twilio, retell-telnyx or custom
Example output
{
  "area_code": 415,
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "prod",
      "weight": 1
    }
  ],
  "inbound_sms_agents": [],
  "inbound_webhook_url": null,
  "last_modification_timestamp": 1784646007000,
  "last_modified_time": "2026-07-21T15:00:07Z",
  "nickname": "Front desk",
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "prod",
      "weight": 1
    }
  ],
  "outbound_sms_agents": [],
  "phone_number": "+14157774444",
  "phone_number_pretty": "+1 (415) 777-4444",
  "phone_number_type": "retell-twilio"
}

Update Retell LLM

Change a Retell LLM's prompt, first message, model or knowledge bases, for example to brief an agent before a campaign. Only the fields you fill in change.

Inputs

Retell LLMllm_idtextRequired
The Retell LLM to act on. Pick one, or paste its ID.
Promptgeneral_prompttext
The instructions the agent follows: who it is, what it is for, and what it must not do. Write {{name}} where a dynamic variable goes.
First messagebegin_messagetext
Optional. What the agent says first. Leave blank and the model writes its own opening.
Who speaks firststart_speakertext
Whether the agent opens the conversation or waits.One of: agent (The agent speaks first), user (The agent waits for the caller).
Modelmodeltext
Optional. The text model the agent thinks with. Free text, since Retell adds and retires models often. Leave blank for Retell's default.
Temperaturemodel_temperaturenumber
Optional. How much the model varies its wording, from 0.0 (always the same) to 1.0. Retell's default is 0, which suits tool calling best.From 0.0 to 1.0.
Knowledge basesknowledge_base_idslist
Optional. IDs of knowledge bases the agent may look things up in, as Create knowledge base or List knowledge bases returns them.
Default dynamic variablesdefault_dynamic_variablesobject
Optional. Values for the prompt's {{placeholders}}, used when a call or chat doesn't supply its own.

Outputs

begin_messagetext
What the agent says first, if set
default_dynamic_variablesobject
Values used for dynamic variables a call doesn't set. Key-value pairs of text.
general_prompttext
The instructions the agent follows
general_toolslist
The tools the agent may call
is_publishedtrue/false
Whether this version is published
knowledge_base_idslist
The knowledge bases the agent looks things up in
last_modification_timestampnumber
When it was last changed, in epoch milliseconds
last_modified_timetext
When it was last changed, as ISO 8601
llm_idtext
Retell LLM ID. Use it as the Response Engine ID of a voice or chat agent.
modeltext
The text model it runs on
model_temperaturenumber
How much the model varies its wording, 0 to 1
start_speakertext
agent or user: who speaks first
versionnumber
Version of the Retell LLM
Example output
{
  "begin_message": "Hi {{customer_name}}, this is Ava from Bright Dental.",
  "default_dynamic_variables": {
    "customer_name": "there"
  },
  "general_prompt": "You are Ava, a friendly receptionist for Bright Dental.",
  "general_tools": [
    {
      "description": "End the call when the customer is done.",
      "name": "end_call",
      "type": "end_call"
    }
  ],
  "is_published": false,
  "knowledge_base_ids": [
    "knowledge_base_a456426614174000"
  ],
  "last_modification_timestamp": 1784646007000,
  "last_modified_time": "2026-07-21T15:00:07Z",
  "llm_id": "llm_234sdertfsdsfsdf",
  "model": "gpt-5.6-terra",
  "model_temperature": 0,
  "start_speaker": "agent",
  "version": 0
}

Update voice agent

Change a Retell AI voice agent's voice, name, language, speech rate, webhook or Response Engine. Only the fields you fill in change. Edits go to the agent's latest draft; a published version can't be changed.

Inputs

Voice agentagent_idtextRequired
The voice agent to act on. Pick one, or paste its agent ID.
Voicevoice_idtext
Optional. A new voice for the agent. Leave blank to keep its voice.
Response Engine typeresponse_engine_typetext
Optional. The kind of the new Response Engine, when changing it. Defaults to retell-llm.One of: retell-llm (Retell LLM), conversation-flow (Conversation flow), custom-llm (Custom LLM).
Response Engine IDresponse_engine_idtext
Optional. A different Response Engine for the agent: a Retell LLM ID, a conversation flow ID, or a custom LLM's websocket URL. Leave blank to keep the one it has.
Agent nameagent_nametext
Optional. A name for your own reference, for example 'Appointment reminders'.
Languagelanguagetext
Optional. A new locale, such as en-US, or several separated by commas for an agent that switches languages; the voice must speak them all. Leave blank to keep the agent's.
Speech ratevoice_speednumber
Optional. How fast the agent speaks, from 0.5 (slower) to 2.0 (faster). Leave blank to use Retell's default of 1.0.From 0.5 to 2.0.
Webhook URLwebhook_urltext
Optional. Where Retell sends this agent's events, such as call_ended and call_analyzed. Leave blank to use the account's webhook.

Outputs

agent_idtext
Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
agent_nametext
Name of the agent, blank if it was created without one
is_publishedtrue/false
Whether this version of the agent is published
languagetext
Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
last_modified_timetext
When the agent was last changed, as an ISO 8601 timestamp
response_engine_idtext
The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
response_engine_typetext
retell-llm, conversation-flow, or custom-llm
versionnumber
Version of the agent this record describes
voice_idtext
Voice the agent speaks with
voice_modeltext
Voice model behind the voice, blank when the provider's default applies
voice_speednumber
Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
webhook_urltext
Agent-level webhook for call events, blank when the account webhook applies
Example output
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_name": "Appointment reminders",
  "is_published": false,
  "language": "en-US",
  "last_modified_time": "2026-07-21T15:00:07Z",
  "response_engine_id": "llm_234sdertfsdsfsdf",
  "response_engine_type": "retell-llm",
  "version": 0,
  "voice_id": "retell-Cimo",
  "voice_model": "eleven_flash_v2_5",
  "voice_speed": 1,
  "webhook_url": "https://example.com/retell-events"
}

restful-api.dev

Previous Page

RevenueCat

Next Page

On this page

ActionsAdd knowledge base sourcesBuy phone numberCreate batch callCreate chat agentCreate knowledge baseCreate phone callCreate Retell LLMCreate voice agentCreate voice agent draftCreate web callDelete callDelete chat agentDelete knowledge baseDelete knowledge base sourceDelete Retell LLMDelete voice agentEnd callEnd chatGet callGet chatGet concurrencyGet knowledge baseGet phone numberGet Retell LLMGet voiceGet voice agentList callsList chat agentsList chatsList knowledge basesList phone numbersList Retell LLMsList voice agentsList voicesPublish voice agentSend chat messageSend SMSStart chatUpdate callUpdate phone numberUpdate Retell LLMUpdate voice agent