---
title: Conversation Logs Retrieval
slug: conversation-logs-retrieval
docTags: 
createdAt: 2025-10-28T09:21:43.978Z
---

This guide explains the workflow and endpoints required to retrieve and filter detailed conversation logs from the UNITH platform.

The log retrieval workflow consists of three main steps: **Authentication**, **Getting Conversations**, and **Fetching Session Logs**.

:::hint{type="info"}
You can use our conversational logs frontend to access raw conversational logs [here.](https://labs.unith.ai/conversation-logs-app)
:::

## Step 1: Authentication

### 1.1 Obtain Bearer Token

To access the logs, you must first obtain a **Bearer token** using your account credentials.

**Endpoint:** **POST** `https://platform-api.unith.ai/auth/token`

**Request Body**

```json
{
  "email": "your-email@example.com",
  "secretKey": "your-secret-key"
}
```

**CURL Example**

```json
curl -X POST "https://platform-api.unith.ai/auth/token" \
-H "Content-Type: application/json" \
-d '{
"email": "your-email@example.com",
"secretKey": "your-secret-key"
}'

```

The response will contain a JSON Web Token (JWT) under data.bearer. **Save this token** to use in the subsequent API calls as an Authorization header.

**Response**

```json
{
"data": {
"bearer": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
```

### 1.2 Retrieve Organization ID (Org ID)

Use the token obtained in the previous step to fetch your user profile, which contains your Organization details.

**Endpoint:** **GET** `https://platform-api.unith.ai/user/me`****


```curl
curl -X 'GET' \
  '[https://platform-api.unith.ai/user/me](https://platform-api.unith.ai/user/me)' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken'
```

**Response:**

```curl
{
  "id": "yourUserId",
  "organisation": {
    "id": "thisIsYourOrgId",  
    "publicId": "thisIsYourPublicOrgId",  // <-- Use this ID in all subsequent steps
    ...
  },
  ...
}
```

:::hint{type="info"}
The value of "id" under the "`organisation`" object is your **Org ID**. You will need this ID for **Step 2** and **Step 3**.
:::

## Step 2: Get Conversations (Filtering by Metadata)

Retrieve a list of conversation sessions for your organization within a specified date range.

**Endpoint: GET** `https://api.data.unith.ai/conversations`

### Query Parameters

| **Parameter** | **Required** | **Format/Notes**                                            |
| ------------- | ------------ | ----------------------------------------------------------- |
| `org_id`      | Required     | Your Organization Public ID.                                |
| `start_date`  | Required     | Start date in ISO 8601 format (e.g., 2023-09-03T00:00:00Z). |
| `end_date`    | Required     | End date in ISO 8601 format (e.g., 2026-10-01T00:00:00Z).   |
| `head_id`     | Optional     | Filter by a specific Digital Human Head ID.                 |
| `username`    | **Optional** | Filter conversations by a specific username.                |
| `data_tag`    | **Optional** | Filter conversations by custom data tag                     |

### Headers

- Authorization: Bearer \<token from **Step 1**>

### Filter by Username

The username field is now available as a **separate column** in conversation logs, making it easier to track and analyze user-specific conversations.

**Previous Behavior:**

- Username was included as a suffix in session\_id: "sessionId\_username"
- Required parsing the session ID to extract username

:::hint{type="info"}
The returned session\_id will automatically include the username for easy identification: `"session_id": "{{SessionID}}_{{username}}"`.
:::

**Current Behavior:**

- Username is now available as a dedicated field

:::hint{type="warning"}
* Legacy **session\_id suffix** format is still supported for backward compatibility but will be depreciated in the near future.&#x20;
* **Recommended: Use the dedicated username field for cleaner analytics**
:::

To enable username tracking, define the data-username attribute when embedding the Digital Human:

**HTML Embed Configuration**

```json
<unith-widget
  head_id="UNITH-1595"
  org_id="U-760"
  api_key="YOUR_API_KEY"
  username="alice"
>
</unith-widget>
```

### Response Example

Below is an example of a retrieved conversation, showing the username included in the `session_id.`

```json
"conversations": [
  {
    "session_id": "20ab19bf-942b-4fc8-bf36-1bc4d7d53103_alice",
    "start_time": "2025-09-09T06:45:07.211821",
    "end_time": "2025-09-09T06:46:40.504327",
    "head_id": "UNITH-1595",
    "head_name": null,
    "org_id": "U-760",
    "message_count": 18
  }
]
```

**CURL Example (With Date Range)**

```curl
curl -X GET "https://api.data.unith.ai/conversations?org_id=your-public-org-id&start_date=2023-06-
01T00:00:00Z&end_date=2025-06-01T00:00:00Z&head_id=" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
```

***

### Custom Tracking with data\_tag

The new `data_tag` field enables flexible custom tracking for any use case. This field accepts **any string value of your choice,** allowing you to segment and analyze conversations based on your specific requirements.

**Common Use Cases:**

- **Multi-Domain Tracking:** Track the same Digital Human across different websites
- **Customer Segmentation:** Tag conversations by user type (e.g., "segment\:enterprise", "segment\:trial")
- **Campaign Tracking:** Associate conversations with marketing campaigns (e.g., "campaign\:summer2025")
- **A/B Testing:** Track different variants (e.g., "variant\:control", "variant\:test")

```html
<unith-widget
  head_id="yourHeadId"
  org_id="yourOrgId"
  api_key="yourApiKey"
  username="alice"
  data_tag="domain:example.com"
>
</unith-widget>
```

**Multiple Values Example:**

You can use any delimiter format that suits your needs:

```html
<!-- Colon delimiter -->
<unith-widget data_tag="source:google:campaign:spring2026"></unith-widget>
```

:::hint{type="info"}
The `data_tag` field gives you complete flexibility—use any format or structure that matches your analytics needs.&#x20;
:::

***

## Enhanced Session Metadata

The UNITH platform now includes **enhanced metadata fields** in conversation logs, providing deeper insights into user sessions and enabling more flexible analytics.

### Session Data Fields

**Direct Fields (sent at root level):**

| **Field**       | **What It Stores**                              | **Example**                             |
| --------------- | ----------------------------------------------- | --------------------------------------- |
| `session_id`    | Unique session identifier                       | "20ab19bf-942b-4fc8-bf36-1bc4d7d53103"  |
| `username`      | User's name from session (separate column)      | "john\_doe" or "anonymous"              |
| `data_tag`      | Custom identifier for tracking and segmentation | "nserve\:mobile", "domain\:example.com" |
| `start_time`    | Session start timestamp                         | "2025-09-09T06:45:07.211821"            |
| `end_time`      | Session end timestamp                           | "2025-09-09T06:46:40.504327"            |
| `head_id`       | Digital Human identifier                        | "UNITH-1595"                            |
| `org_id`        | Organization identifier                         | "U-760"                                 |
| `message_count` | Number of messages in conversation              | 18                                      |

**Metadata Fields (extracted from request\_metadata):**

| **Field**        | **What It Stores**          | **Example**                   |
| ---------------- | --------------------------- | ----------------------------- |
| `origin_domain`  | Website where chat happened | "https\://chat.unith.ai"      |
| `device_type`    | User's device               | "desktop", "mobile", "tablet" |
| `browser_family` | User's browser              | "chrome", "firefox", "safari" |
| `language_pref`  | User's language preference  | "en-US", "ja-JP", "de-DE"     |

:::hint{type="info"}
Technical metadata fields (origin\_domain, device\_type, browser\_family, language\_pref) are captured automatically without additional configuration. These fields are **available in both** streaming and legacy Digital Humans.
:::

***

## Step 3: Get Session Logs

Retrieve the detailed message logs (the full transcript) for a specific conversation session.

**Endpoint:** **GET** `https://api.data.unith.ai/sessions/{public_org_id}/{session_id}`

### Path Parameters

- `public_org_id:` Your organization ID.
- `session_id:` The full session ID (including the username suffix, if used) obtained from Step 2.

### Headers

- Authorization: Bearer \<token from Step 1>

### CURL Example

```curl
curl -X GET "https://api.data.unith.ai/sessions/your-public-org-id/session-id-here" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
```

## Complete Workflow Example

This section provides a complete, sequential command line example for retrieving logs.

```json
# Step 1: Get authentication token (stores token in environment variable $TOKEN)
TOKEN=$(curl -s -X POST "[https://platform-api.unith.ai/auth/token](https://platform-api.unith.ai/auth/token)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "secretKey": "your-secret-key"
  }' | jq -r '.data.bearer')
  
# Step 2: Get conversations
curl -X GET "https://api.data.unith.ai/conversations?org_id=your-public-org-id&start_date=2023-06-
01T00:00:00Z&end_date=2025-06-01T00:00:00Z" \
-H "Authorization: Bearer $TOKEN"

# Step 3: Get specific session logs (replace session-id with actual ID from
Step 2)
curl -X GET "https://api.data.unith.ai/sessions/your-public-org-id/session-id-here" \
-H "Authorization: Bearer $TOKEN"
```

## Important Notes

- **Token Expiration:** Bearer tokens have an expiration time of 7 days. If you receive authentication errors, you must generate a new token via the authentication endpoint.
- **Organization ID:** Always ensure you use the correct organization ID associated with your account.
- **Date Format:** All date parameters (start\_date, end\_date) must strictly use the **ISO 8601** format (e.g., YYYY-MM-DDTHH\:mm\:ssZ).
- **Session IDs:** Session IDs are UUIDs retrieved from the conversations endpoint, and will include the optional \_\{\{username}} suffix if configured in the embed code.