Get, list, and delete XUNA AI agent conversations

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}

string

required

The ID of the conversation to retrieve.

conversation = client.conversational_ai.conversations.get(
    conversation_id="conv_xxxxxxxxxxxxxxxxxxxxxxxx"
)
print(conversation.transcript)

const conversation = await client.conversationalAi.conversations.get(
    "conv_xxxxxxxxxxxxxxxxxxxxxxxx"
);
console.log(conversation.transcript);

curl https://api.xuna.ai/v1/convai/conversations/conv_xxxxxxxxxxxxxxxxxxxxxxxx \
  -H "x-api-key: YOUR_API_KEY"

Response fields:

object[]

Turn-by-turn transcript of the conversation, including speaker labels and timestamps.

string

URL to the recorded audio for the conversation.

object

Conversation metadata including start time, end time, duration, and agent ID.

object

Scores and feedback from any evaluation criteria configured on the agent.

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}

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)

const result = await client.conversationalAi.conversations.list({
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});
for (const conv of result.conversations) {
    console.log(conv.conversationId, conv.metadata.startTime);
}

curl "https://api.xuna.ai/v1/convai/conversations?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6" \
  -H "x-api-key: YOUR_API_KEY"

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}

string

required

The ID of the conversation to delete.

client.conversational_ai.conversations.delete(
    conversation_id="conv_xxxxxxxxxxxxxxxxxxxxxxxx"
)
print("Conversation deleted.")

await client.conversationalAi.conversations.delete(
    "conv_xxxxxxxxxxxxxxxxxxxxxxxx"
);
console.log("Conversation deleted.");

curl -X DELETE https://api.xuna.ai/v1/convai/conversations/conv_xxxxxxxxxxxxxxxxxxxxxxxx \
  -H "x-api-key: YOUR_API_KEY"

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}

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://...

const response = await client.conversationalAi.conversations.getSignedUrl({
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});
console.log(response.signedUrl); // wss://...

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}

string

required

The ID of the agent to connect to.

response = client.conversational_ai.conversations.get_token(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
print(response.token)

const response = await client.conversationalAi.conversations.getToken({
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});
console.log(response.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.

Overview

Agents

Telephony

Get, list, and delete XUNA AI agent conversations

Get a conversation

List conversations

Delete a conversation

Get a signed URL

Get a conversation token

​Get a conversation

​List conversations

​Delete a conversation

​Get a signed URL

​Get a conversation token

Get a conversation

List conversations

Delete a conversation

Get a signed URL

Get a conversation token