Get list conversation flows — retell-sdk

v28

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-05-2887246443.7 KB

List all conversation flows that can be attached to an agent.

get/list-conversation-flows

Query parameters

limitinteger

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.

pagination_keystring

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_versioninteger

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

model_temperaturenumber nullable

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

tool_call_strict_modeboolean nullable

Whether to use strict mode for tool calls. Only applicable when using certain supported models.

knowledge_base_idsstring[] nullable

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

start_speaker'user' | 'agent'

Who starts the conversation - user or agent.

begin_after_user_silence_msinteger nullable

If set, the AI will begin the conversation after waiting for the user for the duration (in milliseconds) specified by this attribute. This only applies if the agent is configured to wait for the user to speak first. If not set, the agent will wait indefinitely for the user to speak.

global_promptstring nullable

Global prompt used in every node of the conversation flow.

flex_modeboolean nullable

If enabled, the whole conversation flow will be converted as a Single Prompt agent.

start_node_idstring nullable

ID of the start node in the conversation flow.

default_dynamic_variablesobject nullable

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

is_transfer_llmboolean nullable

Whether this conversation flow is used for transfer LLM.

conversation_flow_idstring required

Unique identifier for the conversation flow

versioninteger required

Version number of the conversation flow

Example response

[
  {
    "model_temperature": 0.7,
    "tool_call_strict_mode": true,
    "knowledge_base_ids": [
      "kb_001",
      "kb_002"
    ],
    "kb_config": {
      "top_k": 3,
      "filter_score": 0.6
    },
    "start_speaker": "agent",
    "begin_after_user_silence_ms": 2000,
    "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"
      }
    ],
    "components": [
      {
        "name": "Customer Information Collector",
        "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"
          }
        ],
        "mcps": [
          {
            "headers": {
              "Authorization": "Bearer 1234567890"
            },
            "query_params": {
              "index": "1",
              "key": "value"
            }
          }
        ],
        "nodes": [
          {
            "id": "collect_info",
            "type": "conversation",
            "instruction": {
              "type": "prompt",
              "text": "Ask the customer for their name and contact information."
            }
          }
        ],
        "start_node_id": "collect_info",
        "begin_tag_display_position": {
          "x": 100,
          "y": 200
        },
        "notes": [
          {
            "id": "note_abc123",
            "content": "Remember to handle edge cases here.",
            "display_position": {
              "x": 300,
              "y": 150
            },
            "size": {
              "width": 200,
              "height": 100
            }
          }
        ]
      }
    ],
    "start_node_id": "start",
    "default_dynamic_variables": {
      "company_name": "Retell Inc",
      "support_hours": "9 AM - 5 PM"
    },
    "begin_tag_display_position": {
      "x": 100,
      "y": 200
    },
    "notes": [
      {
        "id": "note_abc123",
        "content": "Remember to handle edge cases here.",
        "display_position": {
          "x": 300,
          "y": 150
        },
        "size": {
          "width": 200,
          "height": 100
        }
      }
    ],
    "mcps": [
      {
        "headers": {
          "Authorization": "Bearer 1234567890"
        },
        "query_params": {
          "index": "1",
          "key": "value"
        }
      }
    ],
    "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"
          }
        ]
      }
    ]
  }
]