GET /list-agents – Retell AI Retell SDK

List all agents

get/list-agents

Query parameters

limitinteger

Example:50

A limit on the number of objects to be returned. Limit can range between 1 and 1000, and the default is 1000.

pagination_keystring

Example:agent_1ffdb9717444d0e77346838911

The pagination key to continue fetching the next page of agents. Pagination key is represented by a agent id, pagination key and version pair is exclusive (not included in the fetched page). If not set, will start from the beginning.

pagination_key_versioninteger

Specifies the version of the agent associated with the pagination_key. When paginating, both the pagination_key and its version must be provided to ensure consistent ordering and to fetch the next page correctly.

is_latestboolean

Example:true

If true, only return the latest version of each agent.

Response

Successfully retrieved all agents.

agent_idstring required

Unique id of agent.

versioninteger required

Version of the agent.

base_versioninteger nullable

Version that this draft was based on. Null for initial versions.

assigned_tagsstring[]

Tags assigned to this agent version. Preferred tag is listed first.

is_publishedboolean

Whether the agent is published.

agent_namestring nullable

The name of the agent. Only used for your own reference.

version_descriptionstring nullable

Optional description of the agent version. Used for your own reference and documentation.

voice_idstring

Unique voice id used for the agent. Find list of available voices and their preview in Dashboard.

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.

fallback_voice_idsstring[] nullable

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.

voice_temperaturenumber

Controls how stable the voice is. Value ranging from [0,2]. Lower value means more stable, and higher value means more variant speech generation. Check the dashboard to see what provider supports this feature. If unset, default value 1 will apply.

voice_speednumber

Controls speed of voice. Value ranging from [0.5,2]. Lower value means slower speech, while higher value means faster speech rate. If unset, default value 1 will apply.

enable_dynamic_voice_speedboolean

If set to true, will enable dynamic voice speed adjustment based on the user's speech rate and conversation context. If unset, default value false will apply.

enable_dynamic_responsivenessboolean

If set to true, the agent will dynamically adjust how quickly it responds based on the user's speech rate and past turn-taking behavior in the call. If unset, default value false will apply.

volumenumber

If set, will control the volume of the agent. Value ranging from [0,2]. Lower value means quieter agent speech, while higher value means louder agent speech. If unset, default value 1 will apply.

Controls the emotional tone of the agent's voice. Currently supported for Cartesia and Minimax TTS providers. If unset, no emotion will be used.

responsivenessnumber

Controls how responsive is the agent. Value ranging from [0,1]. Lower value means less responsive agent (wait more, respond slower), while higher value means faster exchanges (respond when it can). If unset, default value 1 will apply.

interruption_sensitivitynumber

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.

enable_backchannelboolean

Controls whether the agent would backchannel (agent interjects the speaker with phrases like "yeah", "uh-huh" to signify interest and engagement). Backchannel when enabled tends to show up more in longer user utterances. If not set, agent will not backchannel.

backchannel_frequencynumber

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.

backchannel_wordsstring[] nullable

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.

reminder_trigger_msnumber

If set (in milliseconds), will trigger a reminder to the agent to speak if the user has been silent for the specified duration after some agent speech. Must be a positive number. If unset, default value of 10000 ms (10 s) will apply.

reminder_max_countinteger

If set, controls how many times agent would remind user when user is unresponsive. Must be a non negative integer. If unset, default value of 1 will apply (remind once). Set to 0 to disable agent from reminding.

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 Ambience
convention-hall: Convention hall ambience, with some echo and people chatting in background. Listen to Ambience
summer-outdoor: Summer outdoor ambience with cicada chirping. Listen to Ambience
mountain-outdoor: Mountain outdoor ambience with birds singing. Listen to Ambience
static-noise: Constant static noise. Listen to Ambience
call-center: Call center work noise. Listen to Ambience Set to null to remove ambient sound from this agent.

ambient_sound_volumenumber

If set, will control the volume of the ambient sound. Value ranging from [0,2]. Lower value means quieter ambient sound, while higher value means louder ambient sound. If unset, default value 1 will apply.

webhook_urlstring nullable

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.

webhook_eventsstring[] nullable

Which webhook events this agent should receive. If not set, defaults to call_started, call_ended, call_analyzed.

webhook_timeout_msinteger

The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply.

boosted_keywordsstring[] nullable

Provide a customized list of keywords to bias the transcriber model, so that these words are more likely to get transcribed. Commonly used for names, brands, street, etc. Entries may reference dynamic variables with {{variable}} syntax.

data_storage_setting'everything' | 'everything_except_pii' | 'basic_attributes_only'

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.

data_storage_retention_daysinteger nullable

Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion).

opt_in_signed_urlboolean

Whether this agent opts in for signed URLs for public logs and recordings. When enabled, the generated URLs will include security signatures that restrict access and automatically expire after 24 hours.

signed_url_expiration_msinteger nullable

The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply.

end_call_after_silence_msinteger

If users stay silent for a period after agent speech, end the call. The minimum value allowed is 10,000 ms (10 s). By default, this is set to 600000 (10 min).

max_call_duration_msinteger

Maximum allowed length for the call, will force end the call if reached. The minimum value allowed is 60,000 ms (1 min), and maximum value allowed is 7,200,000 (2 hours). By default, this is set to 3,600,000 (1 hour).

voicemail_messagestring

The message to be played when the call enters a voicemail. Note that this feature is only available for phone calls. If you want to hangup after hitting voicemail, set this to empty string.

voicemail_detection_timeout_msinteger

Configures when to stop running voicemail detection, as it becomes unlikely to hit voicemail after a couple minutes, and keep running it will only have negative impact. The minimum value allowed is 5,000 ms (5 s), and maximum value allowed is 180,000 (3 minutes). By default, this is set to 30,000 (30 s).

Available LLM models for agents.

analysis_successful_promptstring nullable

Prompt to determine whether the post call or chat analysis should mark the interaction as successful. Set to null to use the default prompt.

analysis_summary_promptstring nullable

Prompt to guide how the post call or chat analysis summary should be generated. When unset, the default system prompt is used. Set to null to use the default prompt.

analysis_user_sentiment_promptstring nullable

Prompt to guide how the post call or chat analysis should evaluate user sentiment. When unset, the default system prompt is used. Set to null to use the default prompt.

begin_message_delay_msinteger

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.

ring_duration_msinteger

If set, the phone ringing will last for the specified amount of milliseconds. This applies for both outbound call ringtime, and call transfer ringtime. Default to 30000 (30 s). Valid range is [5000, 300000].

stt_mode'fast' | 'accurate' | 'custom'

If set, determines whether speech to text should focus on latency or accuracy. Default to fast mode. When set to custom, custom_stt_config must be provided.

vocab_specialization'general' | 'medical'

If set, determines the vocabulary set to use for transcription. This setting only applies for English agents, for non English agent, this setting is a no-op. Default to general.

allow_user_dtmfboolean

If set to true, DTMF input will be accepted and processed. If false, any DTMF input will be ignored. Default to true.

allow_dtmf_interruptionboolean

If set to true, DTMF input will interrupt the agent even when interruption_sensitivity is 0. Can be overridden per conversation or subagent node. Default to false.

denoising_mode'no-denoise' | 'noise-cancellation' | 'noise-and-background-speech-cancellation'

If set, determines what denoising mode to use. Use "no-denoise" to bypass all audio denoising. Default to noise-cancellation.

timezonestring nullable

IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set.

last_modification_timestampinteger required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

Example response

[
  {
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "base_version": 12,
    "agent_name": "Jarvis",
    "version_description": "Customer support agent for handling product inquiries",
    "voice_id": "retell-Cimo",
    "fallback_voice_ids": [
      "cartesia-Cimo",
      "minimax-Cimo"
    ],
    "voice_temperature": 1,
    "voice_speed": 1,
    "enable_dynamic_voice_speed": true,
    "enable_dynamic_responsiveness": true,
    "volume": 1,
    "voice_emotion": "calm",
    "responsiveness": 1,
    "interruption_sensitivity": 1,
    "enable_backchannel": true,
    "backchannel_frequency": 0.9,
    "backchannel_words": [
      "yeah",
      "uh-huh"
    ],
    "reminder_trigger_ms": 10000,
    "reminder_max_count": 2,
    "ambient_sound_volume": 1,
    "language": "en-US",
    "webhook_url": "https://webhook-url-here",
    "webhook_timeout_ms": 10000,
    "boosted_keywords": [
      "retell",
      "kroger"
    ],
    "data_storage_setting": "everything",
    "data_storage_retention_days": 30,
    "opt_in_signed_url": true,
    "signed_url_expiration_ms": 86400000,
    "pronunciation_dictionary": [
      {
        "word": "actually",
        "alphabet": "ipa",
        "phoneme": "ˈæktʃuəli"
      }
    ],
    "end_call_after_silence_ms": 600000,
    "max_call_duration_ms": 3600000,
    "voicemail_message": "Hi, please give us a callback.",
    "voicemail_detection_timeout_ms": 30000,
    "voicemail_option": {
      "action": {
        "type": "static_text",
        "text": "Please give us a callback tomorrow at 10am."
      }
    },
    "ivr_option": {
      "action": {
        "type": "hangup"
      }
    },
    "call_screening_option": {
      "agent_identity": "Acme Health scheduling team",
      "call_purpose": "confirming your appointment for tomorrow"
    },
    "post_call_analysis_data": [
      {
        "type": "string",
        "name": "customer_name",
        "description": "The name of the customer.",
        "examples": [
          "John Doe",
          "Jane Smith"
        ]
      }
    ],
    "analysis_successful_prompt": "The agent finished the task and the call was complete without being cutoff.",
    "analysis_summary_prompt": "Summarize the outcome of the conversation in two sentences.",
    "analysis_user_sentiment_prompt": "Evaluate the user's sentiment based on their tone and satisfaction level.",
    "begin_message_delay_ms": 1000,
    "ring_duration_ms": 30000,
    "stt_mode": "fast",
    "vocab_specialization": "general",
    "allow_user_dtmf": true,
    "user_dtmf_options": {
      "termination_key": "#"
    },
    "denoising_mode": "noise-cancellation",
    "timezone": "America/New_York",
    "last_modification_timestamp": 1703413636133
  }
]

Changes

Changed in 18 of the 28 revisions of this API.52893

May 18, 20266342a99901081See the full diff
- ●
  removed the optional property ///// from the response with the status
  response-optional-property-removed
May 11, 20267c30e3ea25362See the full diff
- ●
  added the new s2.1-pro enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new sonic-3.5 enum value to the ///// response property for the response status
  response-property-enum-value-added
May 8, 2026a109c375a3671See the full diff
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
May 7, 2026f1a0d7c1e36c7See the full diff
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////// to the response with the status
  response-optional-property-added
- ○
  added the optional property ////// to the response with the status
  response-optional-property-added
- ○
  added subschema #1 subschema #3 to the response property allOf list for the response status
  response-property-all-of-added
- ○
  removed subschema #1 subschema #3 from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed the gemini-2.5-flash enum value from the ///// response property for the response status
  response-property-enum-value-removed
Apr 28, 20261b4a9d84942a114See the full diff
- ▲
  the ////// response's property type changed from string to no type for status
  response-property-type-changed
- ●
  added the new gpt-5.5 enum value to the ///// response property for the response status
  response-property-enum-value-added
- ○
  added to the ////// response property allOf list for the response status
  response-property-all-of-added
- ○
  removed the azure enum value from the ////// response property for the response status
  response-property-enum-value-removed
- ○
  removed the deepgram enum value from the ////// response property for the response status
  response-property-enum-value-removed
- ○
  removed the soniox enum value from the ////// response property for the response status
  response-property-enum-value-removed
Apr 27, 2026a44406f743c2264See the full diff
- ▲
  added subschema #2 to the ///// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  the ///// response's property type changed from string to no type for status
  response-property-type-changed
- ○
  removed the af-ZA enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ar-SA enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the az-AZ enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the bg-BG enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the bs-BA enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ca-ES enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the cs-CZ enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the cy-GB enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the da-DK enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the de-DE enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the el-GR enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the en-AU enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the en-GB enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the en-IN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the en-NZ enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the en-US enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the es-419 enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the es-ES enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the fa-IR enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the fi-FI enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the fil-PH enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the fr-CA enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the fr-FR enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the gl-ES enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the he-IL enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the hi-IN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the hr-HR enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the hu-HU enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the hy-AM enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the id-ID enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the is-IS enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the it-IT enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ja-JP enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the kk-KZ enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the kn-IN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ko-KR enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the lt-LT enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the lv-LV enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the mk-MK enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the mr-IN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ms-MY enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the multi enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ne-NP enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the nl-BE enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the nl-NL enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the no-NO enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the pl-PL enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the pt-BR enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the pt-PT enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ro-RO enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ru-RU enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the sk-SK enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the sl-SI enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the sr-RS enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the sv-SE enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the sw-KE enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ta-IN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the th-TH enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the tr-TR enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the uk-UA enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the ur-IN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the vi-VN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the yue-CN enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the zh-CN enum value from the ///// response property for the response status
  response-property-enum-value-removed
Apr 20, 20268ee53928bf3141See the full diff
- ●
  removed the optional property ///// from the response with the status
  response-optional-property-removed
- ●
  added the new gemini-3.1-flash-lite enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new s2-pro enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new soniox enum value to the ////// response property for the response status
  response-property-enum-value-added
- ○
  added the new optional query request parameter is_latest
  new-optional-request-parameter
Apr 1, 202656de19127afb13See the full diff
- ▲
  added to the ////// response property oneOf list for the response status
  response-property-one-of-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  removed from the ////// response property oneOf list for the response status
  response-property-one-of-removed
Mar 19, 20263aa6f6e028ef22See the full diff
- ●
  added the new gpt-5.4-mini enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new gpt-5.4-nano enum value to the ///// response property for the response status
  response-property-enum-value-added
- ○
  removed the sonic-2 enum value from the ///// response property for the response status
  response-property-enum-value-removed
- ○
  removed the sonic-turbo enum value from the ///// response property for the response status
  response-property-enum-value-removed
Mar 17, 2026424df3aa79002See the full diff
- ●
  removed the optional property ///// from the response with the status
  response-optional-property-removed
- ●
  added the new gpt-5.4 enum value to the ///// response property for the response status
  response-property-enum-value-added

Full history (18 revisions)