# Retell AI

> 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.

App · Voice AI · 42 actions. Web page: https://docs.lodol.com/docs/integrations/retell

## Actions

### Add knowledge base sources

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

**Inputs**

- Knowledge base (`knowledge_base_id`, text, required): The knowledge base to act on. Pick one, or paste its ID.
- Texts (`texts`, list): Optional. Texts to add, each an object with a title and the text. Plain text is added too, titled by its first line.
- Web pages (`urls`, list): Optional. Addresses of pages for Retell to read and add, each starting with https://.
- Files (`files`, list): 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_refresh` (true/false): Whether Retell re-reads its pages and connected files daily
- `knowledge_base_id` (text): Knowledge base ID. Add it to a Retell LLM to let an agent use it.
- `knowledge_base_name` (text): The knowledge base's name
- `knowledge_base_sources` (list): Its texts, pages and files, listed once indexing is complete
- `knowledge_base_status` (text): in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
- `last_refreshed_time` (text): When it was last refreshed, as ISO 8601
- `last_refreshed_timestamp` (number): When it was last refreshed, in epoch milliseconds
- `max_chunk_size` (number): Most characters per chunk
- `min_chunk_size` (number): Fewest characters per chunk

**Example output**

```json
{
  "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 code (`area_code`, number): Optional. The three-digit area code you'd like, such as 415. From 200 to 999.
- Exact number (`phone_number`, text): Optional. A specific available number to buy, in international format.
- Country (`country_code`, text): Optional. Where the number is from. Defaults to the United States. One of: `US` (United States), `CA` (Canada).
- Toll-free (`toll_free`, true/false): Optional. Buy a toll-free number, which costs more.
- Carrier (`number_provider`, text): Optional. Who supplies the number. Defaults to Twilio. One of: `twilio`, `telnyx`.
- Nickname (`nickname`, text): Optional. A name for the number, for your own reference.
- Answers calls (`inbound_agent_id`, text): Optional. The voice agent that answers calls to the number.
- Places calls (`outbound_agent_id`, text): Optional. The voice agent that makes calls from the number.
- Inbound webhook URL (`inbound_webhook_url`, text): 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_code` (number): The number's area code
- `inbound_agents` (list): The agents that answer calls to it
- `inbound_sms_agents` (list): The chat agents that answer texts to it
- `inbound_webhook_url` (text): Where Retell asks how to handle each inbound call, if set
- `last_modification_timestamp` (number): When it was last changed, in epoch milliseconds
- `last_modified_time` (text): When it was last changed, as ISO 8601
- `nickname` (text): The name you gave the number
- `outbound_agents` (list): The agents that place calls from it
- `outbound_sms_agents` (list): The chat agents that send texts from it
- `phone_number` (text): The number in E.164 form, such as +14157774444. It is its ID.
- `phone_number_pretty` (text): The number formatted for reading
- `phone_number_type` (text): retell-twilio, retell-telnyx or custom

**Example output**

```json
{
  "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 number (`from_number`, text, required): One of your Retell numbers to call from. Pick one, or type it in international format, such as +14157774444.
- Recipients (`recipients`, list, required): 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 agent (`agent_id`, text): Optional. The agent that makes this call. Leave blank to use the agent the From number is set up with.
- Batch name (`name`, text): Optional. A name for your own reference.
- Start at (`start_at`, date and time): Optional. When to start calling. Leave blank to start now.
- Call from (`window_start`, time): Optional. The earliest time of day to call, in the calling time zone. Leave blank for midnight.
- Call until (`window_end`, time): Optional. The latest time of day to call, in the calling time zone. Leave blank for the end of the day.
- Calling time zone (`window_timezone`, text): Optional. The time zone the calling hours are in. Defaults to America/Los_Angeles.
- Calling days (`window_days`, list): 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 free (`reserved_concurrency`, number): Optional. How many of the account's simultaneous calls to keep free for others, such as inbound calls. At least 0.

**Outputs**

- `batch_call_id` (text): Batch call ID. List calls filters by it to find its calls.
- `call_time_window` (object): The hours calls may be placed in, if any were set
- `from_number` (text): The number the calls are placed from
- `name` (text): The batch call's name
- `scheduled_time` (text): When the calls start, as ISO 8601
- `scheduled_timestamp` (number): When the calls start, in epoch milliseconds
- `total_task_count` (number): How many calls the batch places

**Example output**

```json
{
  "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 type (`response_engine_type`, text): 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 ID (`response_engine_id`, text, required): 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 name (`agent_name`, text): Optional. A name for your own reference, for example 'Appointment reminders'.
- Language (`language`, text): 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 URL (`webhook_url`, text): Optional. Where Retell sends this agent's chat events. Leave blank to use the account's webhook.

**Outputs**

- `agent_id` (text): Chat agent ID. Use with Start chat or Send SMS.
- `agent_name` (text): Name of the agent, blank if it was created without one
- `is_published` (true/false): Whether this version of the agent is published
- `language` (text): Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
- `last_modified_time` (text): When the agent was last changed, as an ISO 8601 timestamp
- `response_engine_id` (text): The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
- `response_engine_type` (text): retell-llm, conversation-flow, or custom-llm
- `version` (number): Version of the agent this record describes
- `webhook_url` (text): Agent-level webhook for chat events, blank when the account webhook applies

**Example output**

```json
{
  "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**

- Name (`name`, text, required): A name for the knowledge base, up to 39 characters.
- Texts (`texts`, list): Optional. Texts to add, each an object with a title and the text. Plain text is added too, titled by its first line.
- Web pages (`urls`, list): Optional. Addresses of pages for Retell to read and add, each starting with https://.
- Files (`files`, list): Optional. Documents to add, up to 25 at once and 50 MB each. Upload them, or use files from an earlier step.
- Refresh daily (`enable_auto_refresh`, true/false): Optional. Have Retell re-read the web pages every day, so the knowledge base keeps up with them.

**Outputs**

- `enable_auto_refresh` (true/false): Whether Retell re-reads its pages and connected files daily
- `knowledge_base_id` (text): Knowledge base ID. Add it to a Retell LLM to let an agent use it.
- `knowledge_base_name` (text): The knowledge base's name
- `knowledge_base_sources` (list): Its texts, pages and files, listed once indexing is complete
- `knowledge_base_status` (text): in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
- `last_refreshed_time` (text): When it was last refreshed, as ISO 8601
- `last_refreshed_timestamp` (number): When it was last refreshed, in epoch milliseconds
- `max_chunk_size` (number): Most characters per chunk
- `min_chunk_size` (number): Fewest characters per chunk

**Example output**

```json
{
  "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 number (`from_number`, text, required): One of your Retell numbers to call from. Pick one, or type it in international format, such as +14157774444.
- To number (`to_number`, text, required): The number to contact, in international format, such as +12137774445. A number bought from Retell can only reach US numbers.
- Voice agent (`agent_id`, text): Optional. The agent that makes this call. Leave blank to use the agent the From number is set up with.
- Agent version (`agent_version`, text): 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 variables (`dynamic_variables`, object): Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
- Metadata (`metadata`, object): 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-call (`honor_do_not_call`, true/false): Optional. When on, Retell refuses to contact a number whose contact is marked do not call.

**Outputs**

- `agent_id` (text): The agent that handled the call
- `agent_name` (text): Name of that agent
- `agent_version` (number): Version of the agent the call used
- `call_analysis` (object): Retell's analysis of the call, ready shortly after it ends
- `call_cost` (object): What the call cost
- `call_id` (text): Call ID. Use with Get call, Update call or Delete call.
- `call_status` (text): registered, not_connected, ongoing, ended or error
- `call_type` (text): phone_call or web_call
- `collected_dynamic_variables` (object): Dynamic variables the agent collected during the call
- `data_storage_setting` (text): How much of the call Retell keeps
- `direction` (text): inbound or outbound, for a phone call
- `disconnection_reason` (text): Why the call ended, such as user_hangup or voicemail_reached
- `duration_ms` (number): How long the call lasted, in milliseconds
- `end_time` (text): When the call ended, as ISO 8601
- `end_timestamp` (number): When the call ended, in epoch milliseconds
- `from_number` (text): The calling number, for a phone call
- `metadata` (object): The metadata the call was given
- `public_log_url` (text): Link to the call's debugging log
- `recording_url` (text): Link to the call recording, once it has ended
- `retell_llm_dynamic_variables` (object): The dynamic variables the call was given. Key-value pairs of text.
- `start_time` (text): When the call started, as ISO 8601
- `start_timestamp` (number): When the call started, in epoch milliseconds
- `to_number` (text): The number called, for a phone call
- `transcript` (text): The call's transcript, once it has ended
- `transcript_object` (list): The transcript, one entry per utterance
- `transfer_destination` (text): Where the call was transferred to, if it was

**Example output**

```json
{
  "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**

- Prompt (`general_prompt`, text): 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 message (`begin_message`, text): Optional. What the agent says first. Leave blank and the model writes its own opening.
- Who speaks first (`start_speaker`, text): Whether the agent opens the conversation or waits. One of: `agent` (The agent speaks first), `user` (The agent waits for the caller).
- Model (`model`, text): Optional. The text model the agent thinks with. Free text, since Retell adds and retires models often. Leave blank for Retell's default.
- Temperature (`model_temperature`, number): 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 bases (`knowledge_base_ids`, list): Optional. IDs of knowledge bases the agent may look things up in, as Create knowledge base or List knowledge bases returns them.
- Default dynamic variables (`default_dynamic_variables`, object): Optional. Values for the prompt's {{placeholders}}, used when a call or chat doesn't supply its own.

**Outputs**

- `begin_message` (text): What the agent says first, if set
- `default_dynamic_variables` (object): Values used for dynamic variables a call doesn't set. Key-value pairs of text.
- `general_prompt` (text): The instructions the agent follows
- `general_tools` (list): The tools the agent may call
- `is_published` (true/false): Whether this version is published
- `knowledge_base_ids` (list): The knowledge bases the agent looks things up in
- `last_modification_timestamp` (number): When it was last changed, in epoch milliseconds
- `last_modified_time` (text): When it was last changed, as ISO 8601
- `llm_id` (text): Retell LLM ID. Use it as the Response Engine ID of a voice or chat agent.
- `model` (text): The text model it runs on
- `model_temperature` (number): How much the model varies its wording, 0 to 1
- `start_speaker` (text): agent or user: who speaks first
- `version` (number): Version of the Retell LLM

**Example output**

```json
{
  "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**

- Voice (`voice_id`, text, required): 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 type (`response_engine_type`, text): 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 ID (`response_engine_id`, text, required): 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 name (`agent_name`, text): Optional. A name for your own reference, for example 'Appointment reminders'.
- Language (`language`, text): 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 rate (`voice_speed`, number): 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 URL (`webhook_url`, text): 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_id` (text): Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
- `agent_name` (text): Name of the agent, blank if it was created without one
- `is_published` (true/false): Whether this version of the agent is published
- `language` (text): Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
- `last_modified_time` (text): When the agent was last changed, as an ISO 8601 timestamp
- `response_engine_id` (text): The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
- `response_engine_type` (text): retell-llm, conversation-flow, or custom-llm
- `version` (number): Version of the agent this record describes
- `voice_id` (text): Voice the agent speaks with

**Example output**

```json
{
  "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 agent (`agent_id`, text, required): The voice agent to act on. Pick one, or paste its agent ID.
- Copy from version (`base_version`, number): Optional. The version number to copy. Leave blank for the latest version. At least 0.

**Outputs**

- `agent_id` (text): Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
- `agent_name` (text): Name of the agent, blank if it was created without one
- `is_published` (true/false): Whether this version of the agent is published
- `language` (text): Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
- `last_modified_time` (text): When the agent was last changed, as an ISO 8601 timestamp
- `response_engine_id` (text): The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
- `response_engine_type` (text): retell-llm, conversation-flow, or custom-llm
- `version` (number): Version of the agent this record describes
- `voice_id` (text): Voice the agent speaks with
- `voice_model` (text): Voice model behind the voice, blank when the provider's default applies
- `voice_speed` (number): Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
- `webhook_url` (text): Agent-level webhook for call events, blank when the account webhook applies

**Example output**

```json
{
  "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 agent (`agent_id`, text, required): The voice agent that takes the call.
- Agent version (`agent_version`, text): 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 variables (`dynamic_variables`, object): Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
- Metadata (`metadata`, object): 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_token` (text): Token a browser joins the call with. Pass it to your web page.
- `call_id` (text): Call ID. Use with Get call once the call is over.
- `expires_at` (number): When the access token expires, in epoch milliseconds
- `expires_time` (text): When the access token expires, as ISO 8601
- `ice_servers` (list): ICE servers the browser configures before connecting
- `transport` (text): The connection transport to select in the web client

**Example output**

```json
{
  "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 ID (`call_id`, text, required): The call's ID, as Create phone call or List calls returns it.

**Outputs**

- `call_id` (text): The call's ID
- `deleted` (true/false): True once the call is deleted

**Example output**

```json
{
  "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 agent (`agent_id`, text, required): The chat agent to act on. Pick one, or paste its agent ID.

**Outputs**

- `agent_id` (text): The agent's ID
- `deleted` (true/false): True once the agent is deleted

**Example output**

```json
{
  "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 base (`knowledge_base_id`, text, required): The knowledge base to act on. Pick one, or paste its ID.

**Outputs**

- `deleted` (true/false): True once the knowledge base is deleted
- `knowledge_base_id` (text): The knowledge base's ID

**Example output**

```json
{
  "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 base (`knowledge_base_id`, text, required): The knowledge base to act on. Pick one, or paste its ID.
- Source ID (`source_id`, text, required): The source to remove, as Get knowledge base lists it under its sources.

**Outputs**

- `enable_auto_refresh` (true/false): Whether Retell re-reads its pages and connected files daily
- `knowledge_base_id` (text): Knowledge base ID. Add it to a Retell LLM to let an agent use it.
- `knowledge_base_name` (text): The knowledge base's name
- `knowledge_base_sources` (list): Its texts, pages and files, listed once indexing is complete
- `knowledge_base_status` (text): in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
- `last_refreshed_time` (text): When it was last refreshed, as ISO 8601
- `last_refreshed_timestamp` (number): When it was last refreshed, in epoch milliseconds
- `max_chunk_size` (number): Most characters per chunk
- `min_chunk_size` (number): Fewest characters per chunk

**Example output**

```json
{
  "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 LLM (`llm_id`, text, required): The Retell LLM to act on. Pick one, or paste its ID.
- Delete even if in use (`force`, true/false): Optional. Delete it even though agents use it, which leaves those agents without a Response Engine.

**Outputs**

- `deleted` (true/false): True once the Retell LLM is deleted
- `llm_id` (text): The Retell LLM's ID

**Example output**

```json
{
  "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 agent (`agent_id`, text, required): The voice agent to act on. Pick one, or paste its agent ID.

**Outputs**

- `agent_id` (text): The agent's ID
- `deleted` (true/false): True once the agent is deleted

**Example output**

```json
{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "deleted": true
}
```

### End call

Hang up a Retell AI call that is in progress.

**Inputs**

- Call ID (`call_id`, text, required): The call's ID, as Create phone call or List calls returns it.

**Outputs**

- `call_id` (text): The call's ID
- `ended` (true/false): True once the call is ended

**Example output**

```json
{
  "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "ended": true
}
```

### End chat

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

**Inputs**

- Chat ID (`chat_id`, text, required): The chat's ID, as Start chat, Send SMS or List chats returns it.

**Outputs**

- `chat_id` (text): The chat's ID
- `ended` (true/false): True once the chat is ended

**Example output**

```json
{
  "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 ID (`call_id`, text, required): The call's ID, as Create phone call or List calls returns it.

**Outputs**

- `agent_id` (text): The agent that handled the call
- `agent_name` (text): Name of that agent
- `agent_version` (number): Version of the agent the call used
- `call_analysis` (object): Retell's analysis of the call, ready shortly after it ends
- `call_cost` (object): What the call cost
- `call_id` (text): Call ID. Use with Get call, Update call or Delete call.
- `call_status` (text): registered, not_connected, ongoing, ended or error
- `call_type` (text): phone_call or web_call
- `collected_dynamic_variables` (object): Dynamic variables the agent collected during the call
- `data_storage_setting` (text): How much of the call Retell keeps
- `direction` (text): inbound or outbound, for a phone call
- `disconnection_reason` (text): Why the call ended, such as user_hangup or voicemail_reached
- `duration_ms` (number): How long the call lasted, in milliseconds
- `end_time` (text): When the call ended, as ISO 8601
- `end_timestamp` (number): When the call ended, in epoch milliseconds
- `from_number` (text): The calling number, for a phone call
- `metadata` (object): The metadata the call was given
- `public_log_url` (text): Link to the call's debugging log
- `recording_url` (text): Link to the call recording, once it has ended
- `retell_llm_dynamic_variables` (object): The dynamic variables the call was given. Key-value pairs of text.
- `start_time` (text): When the call started, as ISO 8601
- `start_timestamp` (number): When the call started, in epoch milliseconds
- `to_number` (text): The number called, for a phone call
- `transcript` (text): The call's transcript, once it has ended
- `transcript_object` (list): The transcript, one entry per utterance
- `transfer_destination` (text): Where the call was transferred to, if it was

**Example output**

```json
{
  "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 ID (`chat_id`, text, required): The chat's ID, as Start chat, Send SMS or List chats returns it.

**Outputs**

- `agent_id` (text): The chat agent in the conversation
- `chat_analysis` (object): Retell's analysis of the chat, ready once it has ended
- `chat_cost` (object): What the chat cost
- `chat_id` (text): Chat ID. Use with Send chat message, Get chat or End chat.
- `chat_status` (text): ongoing, ended or error
- `chat_type` (text): api_chat or sms_chat
- `collected_dynamic_variables` (object): Dynamic variables the agent collected during the chat
- `end_time` (text): When the chat ended, as ISO 8601
- `end_timestamp` (number): When the chat ended, in epoch milliseconds
- `message_with_tool_calls` (list): The conversation, one entry per message or tool call
- `metadata` (object): The metadata the chat was given
- `retell_llm_dynamic_variables` (object): The dynamic variables the chat was given. Key-value pairs of text.
- `start_time` (text): When the chat started, as ISO 8601
- `start_timestamp` (number): When the chat started, in epoch milliseconds
- `transcript` (text): The conversation so far
- `version` (number): Version of the chat agent

**Example output**

```json
{
  "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_concurrency` (number): The free part of that limit
- `concurrency_burst_enabled` (true/false): Whether calls may go over the limit, at a surcharge
- `concurrency_burst_limit` (number): The ceiling while bursting, or 0 when it is off
- `concurrency_limit` (number): How many calls the account may run at once
- `concurrency_purchase_limit` (number): The most that may be bought
- `current_concurrency` (number): How many calls are running now
- `purchased_concurrency` (number): The bought part of that limit
- `remaining_purchase_limit` (number): How much more may still be bought
- `reserved_inbound_concurrency` (number): Places kept free for inbound calls

**Example output**

```json
{
  "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 base (`knowledge_base_id`, text, required): The knowledge base to act on. Pick one, or paste its ID.

**Outputs**

- `enable_auto_refresh` (true/false): Whether Retell re-reads its pages and connected files daily
- `knowledge_base_id` (text): Knowledge base ID. Add it to a Retell LLM to let an agent use it.
- `knowledge_base_name` (text): The knowledge base's name
- `knowledge_base_sources` (list): Its texts, pages and files, listed once indexing is complete
- `knowledge_base_status` (text): in_progress while Retell reads the sources, then complete; error if it could not, refreshing_in_progress during a refresh
- `last_refreshed_time` (text): When it was last refreshed, as ISO 8601
- `last_refreshed_timestamp` (number): When it was last refreshed, in epoch milliseconds
- `max_chunk_size` (number): Most characters per chunk
- `min_chunk_size` (number): Fewest characters per chunk

**Example output**

```json
{
  "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 number (`phone_number`, text, required): One of your Retell numbers. Pick one, or type it in international format, such as +14157774444.

**Outputs**

- `area_code` (number): The number's area code
- `inbound_agents` (list): The agents that answer calls to it
- `inbound_sms_agents` (list): The chat agents that answer texts to it
- `inbound_webhook_url` (text): Where Retell asks how to handle each inbound call, if set
- `last_modification_timestamp` (number): When it was last changed, in epoch milliseconds
- `last_modified_time` (text): When it was last changed, as ISO 8601
- `nickname` (text): The name you gave the number
- `outbound_agents` (list): The agents that place calls from it
- `outbound_sms_agents` (list): The chat agents that send texts from it
- `phone_number` (text): The number in E.164 form, such as +14157774444. It is its ID.
- `phone_number_pretty` (text): The number formatted for reading
- `phone_number_type` (text): retell-twilio, retell-telnyx or custom

**Example output**

```json
{
  "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 LLM (`llm_id`, text, required): The Retell LLM to act on. Pick one, or paste its ID.
- Version (`version`, number): Optional. The version number to read. Leave blank for the latest. At least 0.

**Outputs**

- `begin_message` (text): What the agent says first, if set
- `default_dynamic_variables` (object): Values used for dynamic variables a call doesn't set. Key-value pairs of text.
- `general_prompt` (text): The instructions the agent follows
- `general_tools` (list): The tools the agent may call
- `is_published` (true/false): Whether this version is published
- `knowledge_base_ids` (list): The knowledge bases the agent looks things up in
- `last_modification_timestamp` (number): When it was last changed, in epoch milliseconds
- `last_modified_time` (text): When it was last changed, as ISO 8601
- `llm_id` (text): Retell LLM ID. Use it as the Response Engine ID of a voice or chat agent.
- `model` (text): The text model it runs on
- `model_temperature` (number): How much the model varies its wording, 0 to 1
- `start_speaker` (text): agent or user: who speaks first
- `version` (number): Version of the Retell LLM

**Example output**

```json
{
  "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**

- Voice (`voice_id`, text, required): The voice to fetch. Pick one, or paste its voice ID.

**Outputs**

- `accent` (text): Its accent, such as American
- `age` (text): How old it sounds, such as Young
- `gender` (text): male or female
- `preview_audio_url` (text): Link to a sample of it
- `provider` (text): Who supplies it, such as elevenlabs or cartesia
- `voice_id` (text): Voice ID. Use it as the Voice of a voice agent.
- `voice_name` (text): The voice's name

**Example output**

```json
{
  "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 ID (`agent_id`, text, required): The agent's ID, as returned by Create voice agent or List voice agents.
- Version (`version`, text): 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_id` (text): Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
- `agent_name` (text): Name of the agent, blank if it was created without one
- `is_published` (true/false): Whether this version of the agent is published
- `language` (text): Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
- `last_modified_time` (text): When the agent was last changed, as an ISO 8601 timestamp
- `response_engine_id` (text): The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
- `response_engine_type` (text): retell-llm, conversation-flow, or custom-llm
- `version` (number): Version of the agent this record describes
- `voice_id` (text): Voice the agent speaks with
- `voice_model` (text): Voice model behind the voice, blank when the provider's default applies
- `voice_speed` (number): Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
- `webhook_url` (text): Agent-level webhook for call events, blank when the account webhook applies

**Example output**

```json
{
  "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 agent (`agent_id`, text): Optional. Only this agent's calls.
- Status (`call_status`, list): Optional. Only calls in these states. One or more of: `not_connected` (Not connected), `ongoing` (In progress), `ended`, `error` (Failed).
- Direction (`direction`, text): Optional. Only inbound or only outbound calls. One of: `inbound`, `outbound`.
- Call type (`call_type`, text): Optional. Only phone calls or only web calls. One of: `phone_call` (Phone call), `web_call` (Web call).
- From number (`from_number`, text): Optional. Only calls from this number, in international format.
- To number (`to_number`, text): Optional. Only calls to this number, in international format.
- Batch call ID (`batch_call_id`, text): Optional. Only the calls a batch call placed, by the ID Create batch call returns.
- Started on or after (`started_after`, date and time): Optional. Only those that started at or after this moment.
- Started on or before (`started_before`, date and time): Optional. Only those that started at or before this moment.
- Maximum records (`limit`, number): The most records to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`.
- Order (`sort_order`, text): Newest or oldest first, by start time. Defaults to newest first. One of: `descending` (Newest first), `ascending` (Oldest first). Default: `descending`.
- Page cursor (`pagination_key`, text): Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

**Outputs**

- `calls` (list): The calls on this page, newest first
- `has_more` (true/false): Whether another page is available
- `pagination_key` (text): Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.

**Example output**

```json
{
  "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**

- Search (`query`, text): Optional. Only include agents whose name or ID contains this text. Leave blank for every agent.
- Maximum agents (`limit`, number): The most agents to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`.
- Page cursor (`pagination_key`, text): Optional. Pass the 'pagination_key' from a previous run to fetch the next page of agents.

**Outputs**

- `agents` (list): Agents on this page, most recently modified first
- `has_more` (true/false): Whether another page is available
- `pagination_key` (text): Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.

**Example output**

```json
{
  "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 agent (`agent_id`, text): Optional. Only this agent's chats.
- Status (`chat_status`, list): Optional. Only chats in these states. One or more of: `ongoing` (In progress), `ended`, `error` (Failed).
- Chat type (`chat_type`, text): Optional. Only API chats or only SMS conversations. One of: `api_chat` (API chat), `sms_chat` (SMS).
- Started on or after (`started_after`, date and time): Optional. Only those that started at or after this moment.
- Started on or before (`started_before`, date and time): Optional. Only those that started at or before this moment.
- Maximum records (`limit`, number): The most records to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`.
- Order (`sort_order`, text): Newest or oldest first, by start time. Defaults to newest first. One of: `descending` (Newest first), `ascending` (Oldest first). Default: `descending`.
- Page cursor (`pagination_key`, text): Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

**Outputs**

- `chats` (list): The chats on this page, newest first
- `has_more` (true/false): Whether another page is available
- `pagination_key` (text): Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.

**Example output**

```json
{
  "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**

- `count` (number): How many knowledge bases there are
- `knowledge_bases` (list): Every knowledge base on the account

**Example output**

```json
{
  "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 records (`limit`, number): The most records to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`.
- Page cursor (`pagination_key`, text): Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

**Outputs**

- `has_more` (true/false): Whether another page is available
- `pagination_key` (text): Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.
- `phone_numbers` (list): The numbers on this page

**Example output**

```json
{
  "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 records (`limit`, number): The most records to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`.
- Page cursor (`pagination_key`, text): Optional. Pass the 'pagination_key' from a previous run to fetch the next page.

**Outputs**

- `has_more` (true/false): Whether another page is available
- `llms` (list): The Retell LLMs on this page
- `pagination_key` (text): Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.

**Example output**

```json
{
  "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**

- Search (`query`, text): Optional. Only include agents whose name or ID contains this text. Leave blank for every agent.
- Maximum agents (`limit`, number): The most agents to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`.
- Page cursor (`pagination_key`, text): Optional. Pass the 'pagination_key' from a previous run to fetch the next page of agents.

**Outputs**

- `agents` (list): Agents on this page, most recently modified first
- `has_more` (true/false): Whether another page is available
- `pagination_key` (text): Cursor for the next page, or empty when there are no more. Pass it back as Page cursor.

**Example output**

```json
{
  "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**

- Provider (`provider`, text): Optional. Only this provider's voices. One of: `elevenlabs`, `openai`, `cartesia`, `minimax`, `fish_audio` (Fish Audio), `inworld`, `platform` (Retell).
- Gender (`gender`, text): Optional. Only female or only male voices. One of: `female`, `male`.
- Accent (`accent`, text): Optional. Only voices whose accent contains this text, such as British.
- Name contains (`name_contains`, text): Optional. Only voices whose name contains this text.

**Outputs**

- `count` (number): How many matched
- `voices` (list): The voices that matched

**Example output**

```json
{
  "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 agent (`agent_id`, text, required): The voice agent to act on. Pick one, or paste its agent ID.
- Version (`version`, number): 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 title (`version_title`, text): Optional. A title for the version, for your own reference.
- Version notes (`version_description`, text): Optional. What changed in this version.

**Outputs**

- `agent_id` (text): Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
- `agent_name` (text): Name of the agent, blank if it was created without one
- `is_published` (true/false): Whether this version of the agent is published
- `language` (text): Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
- `last_modified_time` (text): When the agent was last changed, as an ISO 8601 timestamp
- `response_engine_id` (text): The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
- `response_engine_type` (text): retell-llm, conversation-flow, or custom-llm
- `version` (number): Version of the agent this record describes
- `voice_id` (text): Voice the agent speaks with
- `voice_model` (text): Voice model behind the voice, blank when the provider's default applies
- `voice_speed` (number): Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
- `webhook_url` (text): Agent-level webhook for call events, blank when the account webhook applies

**Example output**

```json
{
  "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 ID (`chat_id`, text, required): The chat's ID, as Start chat, Send SMS or List chats returns it.
- Message (`message`, text, required): What the person says to the agent.

**Outputs**

- `chat_id` (text): The chat's ID
- `messages` (list): Everything the agent did in answer, tool calls included
- `reply` (text): The agent's answer: its messages, without the tool calls between them

**Example output**

```json
{
  "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 number (`from_number`, text, required): One of your Retell numbers with SMS enabled. Pick one, or type it in international format.
- To number (`to_number`, text, required): The number to text, in international format, such as +12137774445.
- Chat agent (`agent_id`, text): Optional. The chat agent that texts. Leave blank to use the agent the From number sends texts with.
- Agent version (`agent_version`, text): 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 variables (`dynamic_variables`, object): Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
- Metadata (`metadata`, object): 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-call (`honor_do_not_call`, true/false): Optional. When on, Retell refuses to contact a number whose contact is marked do not call.

**Outputs**

- `agent_id` (text): The chat agent in the conversation
- `chat_analysis` (object): Retell's analysis of the chat, ready once it has ended
- `chat_cost` (object): What the chat cost
- `chat_id` (text): Chat ID. Use with Send chat message, Get chat or End chat.
- `chat_status` (text): ongoing, ended or error
- `chat_type` (text): api_chat or sms_chat
- `collected_dynamic_variables` (object): Dynamic variables the agent collected during the chat
- `end_time` (text): When the chat ended, as ISO 8601
- `end_timestamp` (number): When the chat ended, in epoch milliseconds
- `message_with_tool_calls` (list): The conversation, one entry per message or tool call
- `metadata` (object): The metadata the chat was given
- `retell_llm_dynamic_variables` (object): The dynamic variables the chat was given. Key-value pairs of text.
- `start_time` (text): When the chat started, as ISO 8601
- `start_timestamp` (number): When the chat started, in epoch milliseconds
- `transcript` (text): The conversation so far
- `version` (number): Version of the chat agent

**Example output**

```json
{
  "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 agent (`agent_id`, text, required): The chat agent to act on. Pick one, or paste its agent ID.
- Agent version (`agent_version`, text): 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 variables (`dynamic_variables`, object): Optional. Values for the {{placeholders}} in the agent's prompt, such as customer_name. Each value is sent as text.
- Metadata (`metadata`, object): 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_id` (text): The chat agent in the conversation
- `chat_analysis` (object): Retell's analysis of the chat, ready once it has ended
- `chat_cost` (object): What the chat cost
- `chat_id` (text): Chat ID. Use with Send chat message, Get chat or End chat.
- `chat_status` (text): ongoing, ended or error
- `chat_type` (text): api_chat or sms_chat
- `collected_dynamic_variables` (object): Dynamic variables the agent collected during the chat
- `end_time` (text): When the chat ended, as ISO 8601
- `end_timestamp` (number): When the chat ended, in epoch milliseconds
- `message_with_tool_calls` (list): The conversation, one entry per message or tool call
- `metadata` (object): The metadata the chat was given
- `retell_llm_dynamic_variables` (object): The dynamic variables the chat was given. Key-value pairs of text.
- `start_time` (text): When the chat started, as ISO 8601
- `start_timestamp` (number): When the chat started, in epoch milliseconds
- `transcript` (text): The conversation so far
- `version` (number): Version of the chat agent

**Example output**

```json
{
  "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 ID (`call_id`, text, required): The call's ID, as Create phone call or List calls returns it.
- Metadata (`metadata`, object): Optional. New metadata for the call, replacing what it has. Up to 50 kB.
- Data kept (`data_storage_setting`, text): 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 attributes (`custom_attributes`, object): Optional. Values for attributes set up under Call History > Actions > Custom attributes in the Retell dashboard, keyed by each attribute's ID.

**Outputs**

- `agent_id` (text): The agent that handled the call
- `agent_name` (text): Name of that agent
- `agent_version` (number): Version of the agent the call used
- `call_analysis` (object): Retell's analysis of the call, ready shortly after it ends
- `call_cost` (object): What the call cost
- `call_id` (text): Call ID. Use with Get call, Update call or Delete call.
- `call_status` (text): registered, not_connected, ongoing, ended or error
- `call_type` (text): phone_call or web_call
- `collected_dynamic_variables` (object): Dynamic variables the agent collected during the call
- `data_storage_setting` (text): How much of the call Retell keeps
- `direction` (text): inbound or outbound, for a phone call
- `disconnection_reason` (text): Why the call ended, such as user_hangup or voicemail_reached
- `duration_ms` (number): How long the call lasted, in milliseconds
- `end_time` (text): When the call ended, as ISO 8601
- `end_timestamp` (number): When the call ended, in epoch milliseconds
- `from_number` (text): The calling number, for a phone call
- `metadata` (object): The metadata the call was given
- `public_log_url` (text): Link to the call's debugging log
- `recording_url` (text): Link to the call recording, once it has ended
- `retell_llm_dynamic_variables` (object): The dynamic variables the call was given. Key-value pairs of text.
- `start_time` (text): When the call started, as ISO 8601
- `start_timestamp` (number): When the call started, in epoch milliseconds
- `to_number` (text): The number called, for a phone call
- `transcript` (text): The call's transcript, once it has ended
- `transcript_object` (list): The transcript, one entry per utterance
- `transfer_destination` (text): Where the call was transferred to, if it was

**Example output**

```json
{
  "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 number (`phone_number`, text, required): One of your Retell numbers. Pick one, or type it in international format, such as +14157774444.
- Answers calls (`inbound_agent_id`, text): Optional. The voice agent that answers calls to the number.
- Places calls (`outbound_agent_id`, text): Optional. The voice agent that makes calls from the number.
- Answers texts (`inbound_sms_agent_id`, text): Optional. The chat agent that answers texts to the number.
- Sends texts (`outbound_sms_agent_id`, text): Optional. The chat agent that sends texts from the number.
- Nickname (`nickname`, text): Optional. A name for the number, for your own reference.
- Inbound webhook URL (`inbound_webhook_url`, text): 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_code` (number): The number's area code
- `inbound_agents` (list): The agents that answer calls to it
- `inbound_sms_agents` (list): The chat agents that answer texts to it
- `inbound_webhook_url` (text): Where Retell asks how to handle each inbound call, if set
- `last_modification_timestamp` (number): When it was last changed, in epoch milliseconds
- `last_modified_time` (text): When it was last changed, as ISO 8601
- `nickname` (text): The name you gave the number
- `outbound_agents` (list): The agents that place calls from it
- `outbound_sms_agents` (list): The chat agents that send texts from it
- `phone_number` (text): The number in E.164 form, such as +14157774444. It is its ID.
- `phone_number_pretty` (text): The number formatted for reading
- `phone_number_type` (text): retell-twilio, retell-telnyx or custom

**Example output**

```json
{
  "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 LLM (`llm_id`, text, required): The Retell LLM to act on. Pick one, or paste its ID.
- Prompt (`general_prompt`, text): 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 message (`begin_message`, text): Optional. What the agent says first. Leave blank and the model writes its own opening.
- Who speaks first (`start_speaker`, text): Whether the agent opens the conversation or waits. One of: `agent` (The agent speaks first), `user` (The agent waits for the caller).
- Model (`model`, text): Optional. The text model the agent thinks with. Free text, since Retell adds and retires models often. Leave blank for Retell's default.
- Temperature (`model_temperature`, number): 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 bases (`knowledge_base_ids`, list): Optional. IDs of knowledge bases the agent may look things up in, as Create knowledge base or List knowledge bases returns them.
- Default dynamic variables (`default_dynamic_variables`, object): Optional. Values for the prompt's {{placeholders}}, used when a call or chat doesn't supply its own.

**Outputs**

- `begin_message` (text): What the agent says first, if set
- `default_dynamic_variables` (object): Values used for dynamic variables a call doesn't set. Key-value pairs of text.
- `general_prompt` (text): The instructions the agent follows
- `general_tools` (list): The tools the agent may call
- `is_published` (true/false): Whether this version is published
- `knowledge_base_ids` (list): The knowledge bases the agent looks things up in
- `last_modification_timestamp` (number): When it was last changed, in epoch milliseconds
- `last_modified_time` (text): When it was last changed, as ISO 8601
- `llm_id` (text): Retell LLM ID. Use it as the Response Engine ID of a voice or chat agent.
- `model` (text): The text model it runs on
- `model_temperature` (number): How much the model varies its wording, 0 to 1
- `start_speaker` (text): agent or user: who speaks first
- `version` (number): Version of the Retell LLM

**Example output**

```json
{
  "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 agent (`agent_id`, text, required): The voice agent to act on. Pick one, or paste its agent ID.
- Voice (`voice_id`, text): Optional. A new voice for the agent. Leave blank to keep its voice.
- Response Engine type (`response_engine_type`, text): 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 ID (`response_engine_id`, text): 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 name (`agent_name`, text): Optional. A name for your own reference, for example 'Appointment reminders'.
- Language (`language`, text): 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 rate (`voice_speed`, number): 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 URL (`webhook_url`, text): 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_id` (text): Agent ID. Use with Get voice agent, or to place calls with this agent from the Retell dashboard.
- `agent_name` (text): Name of the agent, blank if it was created without one
- `is_published` (true/false): Whether this version of the agent is published
- `language` (text): Locale the agent operates in, for example en-US. Multi-locale agents list every locale, comma separated.
- `last_modified_time` (text): When the agent was last changed, as an ISO 8601 timestamp
- `response_engine_id` (text): The Retell LLM ID, conversation flow ID, or custom LLM websocket URL driving the agent, matching the type above
- `response_engine_type` (text): retell-llm, conversation-flow, or custom-llm
- `version` (number): Version of the agent this record describes
- `voice_id` (text): Voice the agent speaks with
- `voice_model` (text): Voice model behind the voice, blank when the provider's default applies
- `voice_speed` (number): Speech rate from 0.5 to 2; 1 when the agent uses Retell's default
- `webhook_url` (text): Agent-level webhook for call events, blank when the account webhook applies

**Example output**

```json
{
  "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"
}
```