Get Voice Agent
Retrieve details of a specific agent
Authorizations
Path Parameters
Query Parameters
Optional version of the API to use for this request. If not provided, will default to latest version. Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
1 - 20^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$"latest_published"
Response
Successfully retrieved an agent.
Select the voice model used for the selected voice. Each provider has a set of available voice models. Set to null to remove voice model selection, and default ones will apply. Check out dashboard for more details of each voice model.
eleven_flash_v2, eleven_flash_v2_5, eleven_multilingual_v2, eleven_v3, eleven_v3_conversational, eleven_v4, eleven_v4_turbo, sonic-3, sonic-3-latest, sonic-3.5, sonic-3.6, tts-1, gpt-4o-mini-tts, speech-02-turbo, speech-2.8-turbo, s1, s2-pro, s2.1-pro, drama-3, inworld-tts-2, inworld-tts-2-flash, null When TTS provider for the selected voice is experiencing outages, we would use fallback voices listed here for the agent. Voice id and the fallback voice ids must be from different TTS providers. The system would go through the list in order, if the first one in the list is also having outage, it would use the next one. Set to null to remove voice fallback for the agent.
The expressive voice tags Retell pre-teaches the model to use when enable_expressive_mode is true. Custom tags defined in the system prompt are still allowed. If empty, the agent follows general expressive guidance without a fixed tag set.
empathetic, excited, happy, curious, surprised, sigh, clear throat, pause, long pause, emphasis Controls how sensitive the agent is to user interruptions. Value ranging from [0,1]. Lower value means it will take longer / more words for user to interrupt agent, while higher value means it's easier for user to interrupt agent. If unset, default value 1 will apply. When this is set to 0, agent would never be interrupted.
0 <= x <= 11
Only applicable when enable_backchannel is true. Controls how often the agent would backchannel when a backchannel is possible. Value ranging from [0,1]. Lower value means less frequent backchannel, while higher value means more frequent backchannel. If unset, default value 0.8 will apply.
0.9
Only applicable when enable_backchannel is true. A list of words that the agent would use as backchannel. If not set, default backchannel words will apply. Check out backchannel default words for more details. Note that certain voices do not work too well with certain words, so it's recommended to experiment before adding any words.
If set, will add ambient environment sound to the call to make experience more realistic. Currently supports the following options:
coffee-shop: Coffee shop ambience with people chatting in background. Listen to Ambienceconvention-hall: Convention hall ambience, with some echo and people chatting in background. Listen to Ambiencesummer-outdoor: Summer outdoor ambience with cicada chirping. Listen to Ambiencemountain-outdoor: Mountain outdoor ambience with birds singing. Listen to Ambiencestatic-noise: Constant static noise. Listen to Ambiencecall-center: Call center work noise. Listen to Ambience Set tonullto remove ambient sound from this agent.
coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise, call-center, null Specifies what language(s) the agent will operate in. Accepts either a single locale (e.g. en-US) or an array of locales for multilingual agents (e.g. ["en-US","es-ES"]). If unset, defaults to en-US.
en-US, en-IN, en-GB, en-AU, en-NZ, de-DE, es-ES, es-419, hi-IN, fr-FR, fr-CA, ja-JP, pt-PT, pt-BR, zh-CN, ru-RU, it-IT, ko-KR, nl-NL, nl-BE, pl-PL, tr-TR, vi-VN, ro-RO, bg-BG, ca-ES, th-TH, da-DK, fi-FI, el-GR, hu-HU, id-ID, no-NO, sk-SK, sv-SE, lt-LT, lv-LV, cs-CZ, ms-MY, af-ZA, ar-SA, az-AZ, bs-BA, cy-GB, fa-IR, fil-PH, gl-ES, he-IL, hr-HR, hy-AM, is-IS, kk-KZ, kn-IN, mk-MK, mr-IN, ne-NP, sl-SI, sr-RS, sw-KE, ta-IN, ur-IN, yue-CN, uk-UA "en-US"
The webhook for agent to listen to call events. See what events it would get at webhook doc. If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to null to remove webhook url from this agent.
"https://webhook-url-here"
Contact memory settings for phone calls and SMS chats. Creating an agent defaults enable_update to false and enable_read to true. Updates only change the supplied flags; omitted flags stay unchanged and an empty object has no effect. Set a flag to false to disable it. The configuration cannot be cleared. Existing agents without this configuration have both disabled.
Granular setting to manage how Retell stores sensitive data (transcripts, recordings, logs, etc.).
This replaces the deprecated opt_out_sensitive_data_storage field.
everything: Store all data including transcripts, recordings, and logs.everything_except_pii: Store data without PII when PII is detected.basic_attributes_only: Store only basic attributes; no transcripts/recordings/logs. If not set, default value of "everything" will apply.
everything, everything_except_pii, basic_attributes_only "everything"
If set to true, the agent recognizes requests to stop calling or contacting the user, confirms once, and on a clear yes ends the call with disconnection reason user_requested_dnc and sets do_not_call to true on the contact for the user's phone number. If unset, default value false will apply.
false
Post call analysis data to extract from the call. This data will augment the pre-defined variables extracted in the call analysis. This will be available after the call ends.
Post-call analysis item (custom data or voice preset). Use for voice agent post_call_analysis_data; validates only call presets (call_summary, call_successful, user_sentiment).
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
The model to use for post call analysis. Default to gpt-5.6-terra.
gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, gpt-5-nano, gpt-5.1, gpt-5.2, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-5.5, gpt-5.6-terra, gpt-5.6-luna, gpt-6-astra, gpt-6-sol, gpt-6.1-sol, gpt-6.1-terra, gpt-6-luna, tell-1, claude-4.6-sonnet, claude-5-opus, claude-5.5-opus, claude-5-sonnet, claude-5.5-sonnet, claude-5.5-haiku, claude-4.5-haiku, gemini-3.0-flash, gemini-3.1-flash-lite, gemini-3.5-flash, gemini-3.5-flash-lite, gemini-3.6-flash, gemini-3.7-flash, gemini-3.8-flash, gemini-4-hydrogen, gemini-4-carbon, gemini-4-argon, null "gpt-4.1-mini"
If set, will delay the first message by the specified amount of milliseconds, so that it gives user more time to prepare to take the call. Valid range is [0, 5000]. If not set or set to 0, agent will speak immediately. Only applicable when agent speaks first.
1000
Controls the enhancement level for background voice cancellation. Set to 0 to bypass background voice cancellation without BVC charges. Value ranging from [0,1]. Only applicable when denoising_mode is noise-and-background-speech-cancellation. Defaults to 0.8 if no value is configured. Set to null to clear the configured value. Omitting this field preserves the existing value.
0 <= x <= 10.8
Integration (Agent Functions) tools run as a dependency graph during session setup, before the agent's first message. Outputs are injected as dynamic variables. On calls the graph gets one minute unless an outbound caller will be dialed after setup, in which case it gets five minutes. Past that session initialization continues and any remaining tools finish in the background, so their outputs no longer reach the agent's prompt. Set to null to clear.
15A pre-session tool (app / custom / code, discriminated by type) plus its dependency edges. The tool's name is the depends_on handle and must be unique across the agent's session tools. Parameters may set a constant value or a description for the LLM to infer the value. Pre-session inference uses the agent prompt and dynamic variables.
- Option 1
- Option 2
- Option 3
Integration (Agent Functions) tools run as a dependency graph during teardown, after post-call analysis. Each tool can be gated by a condition. On calls the graph is stopped after five minutes so teardown can finish. Set to null to clear.
15A post-session tool with an optional condition. Parameter inference uses the agent prompt, dynamic variables, and conversation. Same tools as PreSessionTool plus send_sms, which is only supported on phone calls — the session is over, so the speak settings are ignored and an inferred sms_content is written by the LLM from the transcript at teardown.
- Option 1
- Option 2
- Option 3
- Option 4

