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

200
application/json

Successfully retrieved conversation flows

The response is of type object[].