Skip to main content
GET
Get Conversation
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.

Authorizations

x-api-key
string
header
required

Path Parameters

conversation_id
string
required

The unique identifier of the conversation.

Example:

"c123456"

Query Parameters

verbose
boolean
default:false

Append verbose=true to the URL to receive additional event data in the response, including:

  • shutdown_reason: The reason why the conversation ended (e.g., "participant_left_timeout")
  • system.pal_joined: When the PAL joined the conversation (preferred for new integrations)
  • system.replica_joined: Legacy duplicate of system.pal_joined with an identical payload; still sent for backward compatibility
  • system.shutdown: When and why the conversation ended
  • application.transcription_ready: The end-of-call transcript. Each entry in properties.transcript has role (user / assistant / system / tool), content, timestamp (Unix epoch float, seconds), seconds_from_start, duration (seconds, float) and inference_id where available.
  • application.perception_analysis: The final visual analysis of the user that includes their appearance, behavior, emotional states, and screen activities
  • application.perception_unavailable: Emitted when perception is enabled but no visual analysis could be produced. properties.reason is one of no_vision_history, empty_summary, or summary_error (for example, the participant's camera was off, no frames were received, or the summary came back empty).
  • application.post_call_action_executed: The outcome of each post-call action Tavus ran after the call, with tool_name, status, and the action's request / response.

This is particularly useful as an alternative to using the callback_url parameter on the create conversation endpoint for retrieving detailed conversation data.

Response

conversation_id
string

A unique identifier for the conversation.

Example:

"c123456"

conversation_name
string

The name of the conversation.

Example:

"A Meeting with Hassaan"

conversation_url
string

A direct link to join the conversation.

Example:

"https://tavus.daily.co/c123456"

callback_url
string

The url that will receive webhooks with updates of the conversation state.

Example:

"https://yourwebsite.com/webhook"

status
string

The status of the conversation.

Example:

"active"

face_id
string

A unique identifier for the face used to create this conversation

Example:

"r90bbd427f71"

pal_id
string

A unique identifier for the PAL used to create this conversation

Example:

"pcb7a34da5fe"

created_at
string

The date and time the conversation was created.

Example:

""

updated_at
string

The date and time of when the conversation was last updated.

Example:

""

events
object[] | null

When verbose=true, additional conversation events (e.g. shutdown, perception analysis payloads, end-of-call transcript).