GET /get-chat/:chat_id — retell-sdk

Retrieve details of a specific chat

get/get-chat/{chat_id}

Path parameters

chat_idstring required

Example:16b980523634a6dc504898cda492e939

Unique id of the chat to be retrieved

Response

Successfully retrieved an chat.

chat_idstring required

Unique id of the chat.

agent_idstring required

Corresponding chat agent id of this chat.

versioninteger nullable

The version of the agent

retell_llm_dynamic_variablesobject

Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

collected_dynamic_variablesobject

Dynamic variables collected from the chat. Only available after the chat ends.

chat_status'ongoing' | 'ended' | 'error' required

Status of chat.

ongoing: Chat session is ongoing, chat agent can receive new message and generate response.
ended: Chat session has ended, and no longer can generate new response.
error: Chat encountered error.

chat_type'api_chat' | 'sms_chat'

Type of the chat

custom_attributesobject

Custom attributes for the chat

start_timestampinteger

Begin timestamp (milliseconds since epoch) of the chat. Available after chat starts.

end_timestampinteger nullable

End timestamp (milliseconds since epoch) of the chat. Available after chat ends.

transcriptstring

Transcription of the chat.

metadataobject

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the chat. Not used for processing. You can later get this field from the chat object.

Example response

{
  "chat_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "version": 1,
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "collected_dynamic_variables": {
    "last_node_name": "Test node"
  },
  "chat_status": "ongoing",
  "chat_type": "api_chat",
  "start_timestamp": 1703302407333,
  "end_timestamp": 1703302428855,
  "transcript": "Agent: hi how are you doing?\nUser: Doing pretty well. How are you?\nAgent: That's great to hear! I'm doing well too, thanks! What's up?\nUser: I don't have anything in particular.\nAgent: Got it, just checking in!\nUser: Alright. See you.\nAgent: have a nice day\n",
  "message_with_tool_calls": [
    {
      "message_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
      "role": "agent",
      "content": "hi how are you doing?",
      "created_timestamp": 1703302428855
    }
  ],
  "chat_cost": {
    "product_costs": [
      {
        "product": "elevenlabs_tts",
        "unit_price": 1,
        "cost": 60
      }
    ],
    "combined_cost": 70
  },
  "chat_analysis": {
    "chat_summary": "The agent messages user to ask question about his purchase inquiry. The agent asked several questions regarding his preference and asked if user would like to book an appointment. The user happily agreed and scheduled an appointment next Monday 10am.",
    "user_sentiment": "Positive",
    "chat_successful": true
  }
}

Changes

Changed in 4 of the 28 revisions of this API.2797

May 12, 20266dff2a12f8662See the full diff
- ▲
  the collected_dynamic_variables/additionalProperties/ response's property type/format changed from / to string/ for status 200
  response-property-type-changed
- ▲
  the retell_llm_dynamic_variables/additionalProperties/ response's property type/format changed from / to string/ for status 200
  response-property-type-changed
Apr 20, 20268ee53928bf312595See the full diff
- ▲
  the message_with_tool_calls/items/oneOf[Message]/ response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ▲
  the message_with_tool_calls/items/oneOf[NodeTransitionMessage]/ response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ▲
  the message_with_tool_calls/items/oneOf[StateTransitionMessage]/ response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ▲
  the message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/ response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ▲
  the message_with_tool_calls/items/oneOf[ToolCallResultMessage]/ response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[Message]/content from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[Message]/created_timestamp from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[Message]/message_id from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[Message]/role from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[NodeTransitionMessage]/created_timestamp from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[NodeTransitionMessage]/message_id from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[NodeTransitionMessage]/role from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[StateTransitionMessage]/created_timestamp from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[StateTransitionMessage]/message_id from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[StateTransitionMessage]/role from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/arguments from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/message_id from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/name from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/role from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/tool_call_id from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallResultMessage]/content from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallResultMessage]/created_timestamp from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallResultMessage]/message_id from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallResultMessage]/role from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property message_with_tool_calls/items/oneOf[ToolCallResultMessage]/tool_call_id from the response with the 200 status
  response-required-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[NodeTransitionMessage]/former_node_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[NodeTransitionMessage]/former_node_name from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[NodeTransitionMessage]/new_node_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[NodeTransitionMessage]/new_node_name from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[StateTransitionMessage]/former_state_name from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[StateTransitionMessage]/new_state_name from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/created_timestamp from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/thought_signature from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property message_with_tool_calls/items/oneOf[ToolCallResultMessage]/successful from the response with the 200 status
  response-optional-property-removed
- ○
  added MessageBase subschema #2 to the message_with_tool_calls/items/oneOf[Message]/ response property allOf list for the response status 200
  response-property-all-of-added
- ○
  added NodeTransitionMessageBase subschema #2 to the message_with_tool_calls/items/oneOf[NodeTransitionMessage]/ response property allOf list for the response status 200
  response-property-all-of-added
- ○
  added StateTransitionMessageBase subschema #2 to the message_with_tool_calls/items/oneOf[StateTransitionMessage]/ response property allOf list for the response status 200
  response-property-all-of-added
- ○
  added ToolCallInvocationMessageBase subschema #2 to the message_with_tool_calls/items/oneOf[ToolCallInvocationMessage]/ response property allOf list for the response status 200
  response-property-all-of-added
- ○
  added ToolCallResultMessageBase subschema #2 to the message_with_tool_calls/items/oneOf[ToolCallResultMessage]/ response property allOf list for the response status 200
  response-property-all-of-added
Feb 23, 2026bcff6899fa2a1See the full diff
- ○
  added the optional property message_with_tool_calls/items/oneOf[ToolCallResultMessage]/successful to the response with the 200 status
  response-optional-property-added
Feb 10, 20260bf5cea5dfcc1See the full diff
- ○
  added the optional property chat_cost/product_costs/items/is_transfer_leg_cost to the response with the 200 status
  response-optional-property-added

Full history