> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xuna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get, list, and delete XUNA AI agent conversations

> Get transcripts, audio, and evaluation data for past conversations, or issue signed URLs and tokens to start new ones via WebSocket or WebRTC.

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}
```

<ParamField path="conversation_id" type="string" required>
  The ID of the conversation to retrieve.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  conversation = client.conversational_ai.conversations.get(
      conversation_id="conv_xxxxxxxxxxxxxxxxxxxxxxxx"
  )
  print(conversation.transcript)
  ```

  ```typescript TypeScript theme={null}
  const conversation = await client.conversationalAi.conversations.get(
      "conv_xxxxxxxxxxxxxxxxxxxxxxxx"
  );
  console.log(conversation.transcript);
  ```

  ```bash cURL theme={null}
  curl https://api.xuna.ai/v1/convai/conversations/conv_xxxxxxxxxxxxxxxxxxxxxxxx \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

**Response fields:**

<ResponseField name="transcript" type="object[]">
  Turn-by-turn transcript of the conversation, including speaker labels and timestamps.
</ResponseField>

<ResponseField name="audio" type="string">
  URL to the recorded audio for the conversation.
</ResponseField>

<ResponseField name="metadata" type="object">
  Conversation metadata including start time, end time, duration, and agent ID.
</ResponseField>

<ResponseField name="evaluation_results" type="object">
  Scores and feedback from any evaluation criteria configured on the agent.
</ResponseField>

<ResponseField name="collected_data" type="object">
  Values collected via data collection tools during the conversation.
</ResponseField>

***

## List conversations

Return a paginated list of conversations, optionally filtered by agent.

```
GET https://api.xuna.ai/v1/convai/conversations?agent_id={agent_id}
```

<ParamField query="agent_id" type="string">
  Filter results to conversations for a specific agent. Omit to list all conversations in your account.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  result = client.conversational_ai.conversations.list(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  )
  for conv in result.conversations:
      print(conv.conversation_id, conv.metadata.start_time)
  ```

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

  ```bash cURL theme={null}
  curl "https://api.xuna.ai/v1/convai/conversations?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

***

## 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}
```

<ParamField path="conversation_id" type="string" required>
  The ID of the conversation to delete.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  client.conversational_ai.conversations.delete(
      conversation_id="conv_xxxxxxxxxxxxxxxxxxxxxxxx"
  )
  print("Conversation deleted.")
  ```

  ```typescript TypeScript theme={null}
  await client.conversationalAi.conversations.delete(
      "conv_xxxxxxxxxxxxxxxxxxxxxxxx"
  );
  console.log("Conversation deleted.");
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.xuna.ai/v1/convai/conversations/conv_xxxxxxxxxxxxxxxxxxxxxxxx \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

<Warning>
  Deletion is permanent. Conversation audio and transcripts cannot be recovered after this call.
</Warning>

***

## 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}
```

<ParamField query="agent_id" type="string" required>
  The ID of the agent to connect to.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = client.conversational_ai.conversations.get_signed_url(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  )
  print(response.signed_url)  # wss://...
  ```

  ```typescript TypeScript theme={null}
  const response = await client.conversationalAi.conversations.getSignedUrl({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  });
  console.log(response.signedUrl); // wss://...
  ```
</CodeGroup>

<ResponseField name="signed_url" type="string" required>
  A `wss://` URL your client opens directly. Valid for a short period — generate a new one for each session.
</ResponseField>

<Tip>
  Call this endpoint from your server and return the signed URL to the client. Never expose your API key to the client.
</Tip>

***

## 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}
```

<ParamField query="agent_id" type="string" required>
  The ID of the agent to connect to.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  response = client.conversational_ai.conversations.get_token(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  )
  print(response.token)
  ```

  ```typescript TypeScript theme={null}
  const response = await client.conversationalAi.conversations.getToken({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  });
  console.log(response.token);
  ```
</CodeGroup>

<ResponseField name="token" type="string" required>
  A short-lived token passed by your client when initiating a WebRTC connection.
</ResponseField>

For a full explanation of when to use signed URLs vs. conversation tokens, see [Authentication](/api-reference/authentication).