Skip to main content
The conversations endpoints give you access to the full history of agent interactions: transcripts, audio recordings, metadata, evaluation results, and collected data variables. You can also use them to generate short-lived credentials for starting new conversations from client-side code.

​
Get a conversation

Retrieve all data for a single completed conversation. 
GET https://api.xuna.ai/v1/convai/conversations/{conversation_id}
​
conversation_id
string
required
The ID of the conversation to retrieve.
conversation = client.conversational_ai.conversations.get(
    conversation_id="conv_xxxxxxxxxxxxxxxxxxxxxxxx"
)
print(conversation.transcript)
Response fields:
​
transcript
object[]
Turn-by-turn transcript of the conversation, including speaker labels and timestamps.
​
audio
string
URL to the recorded audio for the conversation.
​
metadata
object
Conversation metadata including start time, end time, duration, and agent ID.
​
evaluation_results
object
Scores and feedback from any evaluation criteria configured on the agent.
​
collected_data
object
Values collected via data collection tools during the conversation.

​
List conversations

Return a paginated list of conversations, optionally filtered by agent. 
GET https://api.xuna.ai/v1/convai/conversations?agent_id={agent_id}
​
agent_id
string
Filter results to conversations for a specific agent. Omit to list all conversations in your account.
result = client.conversational_ai.conversations.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
for conv in result.conversations:
    print(conv.conversation_id, conv.metadata.start_time)

​
Delete a conversation

Permanently delete a conversation and all its associated data, including audio and transcripts. 
DELETE https://api.xuna.ai/v1/convai/conversations/{conversation_id}
​
conversation_id
string
required
The ID of the conversation to delete.
client.conversational_ai.conversations.delete(
    conversation_id="conv_xxxxxxxxxxxxxxxxxxxxxxxx"
)
print("Conversation deleted.")
Deletion is permanent. Conversation audio and transcripts cannot be recovered after this call.

​
Get a signed URL

Generate a pre-authenticated WebSocket URL so a client can start a conversation without exposing your API key. 
GET https://api.xuna.ai/v1/convai/conversation/get-signed-url?agent_id={agent_id}
​
agent_id
string
required
The ID of the agent to connect to.
response = client.conversational_ai.conversations.get_signed_url(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
print(response.signed_url)  # wss://...
​
signed_url
string
required
A wss:// URL your client opens directly. Valid for a short period — generate a new one for each session.
Call this endpoint from your server and return the signed URL to the client. Never expose your API key to the client.

​
Get a conversation token

Generate a short-lived token for WebRTC-based connections. 
GET https://api.xuna.ai/v1/convai/conversation/token?agent_id={agent_id}
​
agent_id
string
required
The ID of the agent to connect to.
response = client.conversational_ai.conversations.get_token(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
print(response.token)
​
token
string
required
A short-lived token passed by your client when initiating a WebRTC connection.
For a full explanation of when to use signed URLs vs. conversation tokens, see Authentication.