GET
/
list-conversation-flows
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

const conversationFlowResponses = await client.conversationFlow.list();

console.log(conversationFlowResponses);
[
  {
    "global_prompt": "You are a helpful customer service agent.",
    "tools": [
      {
        "type": "custom",
        "name": "get_customer_info",
        "description": "Get customer information from database",
        "tool_id": "tool_001",
        "url": "https://api.example.com/customer",
        "method": "GET"
      }
    ],
    "start_node_id": "start",
    "model_temperature": 0.7,
    "tool_call_strict_mode": true,
    "default_dynamic_variables": {
      "company_name": "Retell Inc",
      "support_hours": "9 AM - 5 PM"
    },
    "knowledge_base_ids": [
      "kb_001",
      "kb_002"
    ],
    "kb_config": {
      "top_k": 3,
      "filter_score": 0.6
    },
    "begin_tag_display_position": {
      "x": 100,
      "y": 200
    },
    "mcps": [
      {
        "name": "<string>",
        "url": "<string>",
        "headers": {
          "Authorization": "Bearer 1234567890"
        },
        "query_params": {
          "index": "1",
          "key": "value"
        },
        "timeout_ms": 123
      }
    ],
    "start_speaker": "agent",
    "model_choice": {
      "type": "cascading",
      "model": "gpt-5",
      "high_priority": true
    },
    "nodes": [
      {
        "id": "start",
        "type": "conversation",
        "instruction": {
          "type": "prompt",
          "text": "Greet the customer and ask how you can help them."
        },
        "edges": [
          {
            "id": "edge_1",
            "transition_condition": {
              "type": "prompt",
              "prompt": "Customer wants to book appointment"
            },
            "destination_node_id": "book_appointment"
          }
        ]
      }
    ],
    "conversation_flow_id": "<string>",
    "version": 123
  }
]

Authorizations

​
Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Query Parameters

​
limit
integer
default:1000

Limit the number of conversation flows returned. Default 1000, Max 1000. To retrieve more than 1000, use pagination_key to continue fetching the next page.

Required range: x <= 1000
​
pagination_key
string

The pagination key to continue fetching the next page of conversation flows. Pagination key is represented by a conversation flow id here, and it's exclusive (not included in the fetched conversation flows). The last conversation flow id from the list conversation flows is usually used as pagination key here. If not set, will start from the beginning.

​
pagination_key_version
integer

Specifies the version of the conversation flow 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.

Response

Successfully retrieved conversation flows

​
conversation_flow_id
string
required

Unique identifier for the conversation flow

​
version
integer
required

Version number of the conversation flow

​
global_prompt
string | null

Global prompt used in every node of the conversation flow.

Example:

"You are a helpful customer service agent."

​
tools
object[] | null

Tools available in the conversation flow.

Example:
[
  {
    "type": "custom",
    "name": "get_customer_info",
    "description": "Get customer information from database",
    "tool_id": "tool_001",
    "url": "https://api.example.com/customer",
    "method": "GET"
  }
]
​
start_node_id
string | null

ID of the start node in the conversation flow.

Example:

"start"

​
model_temperature
number | null

Controls the randomness of the model's responses. Lower values make responses more deterministic.

Required range: 0 <= x <= 1
Example:

0.7

​
tool_call_strict_mode
boolean | null

Whether to use strict mode for tool calls. Only applicable when using structured output models.

Example:

true

​
default_dynamic_variables
object | null

Default dynamic variables that can be referenced throughout the conversation flow.

Example:
{
  "company_name": "Retell Inc",
  "support_hours": "9 AM - 5 PM"
}
​
knowledge_base_ids
string[] | null

Knowledge base IDs for RAG (Retrieval-Augmented Generation).

Example:
["kb_001", "kb_002"]
​
kb_config
object

Knowledge base configuration for RAG retrieval.

​
begin_tag_display_position
object | null

Display position for the begin tag in the frontend.

​
mcps
object[] | null

A list of MCP server configurations to use for this conversation flow.

​
start_speaker
enum<string>

Who starts the conversation - user or agent.

Available options:
user,
agent
Example:

"agent"

​
model_choice
object

The model choice for the conversation flow.

​
nodes
object[]

Array of nodes in the conversation flow.

Example:
[
  {
    "id": "start",
    "type": "conversation",
    "instruction": {
      "type": "prompt",
      "text": "Greet the customer and ask how you can help them."
    },
    "edges": [
      {
        "id": "edge_1",
        "transition_condition": {
          "type": "prompt",
          "prompt": "Customer wants to book appointment"
        },
        "destination_node_id": "book_appointment"
      }
    ]
  }
]