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

# User Engagement Trend API - v2

[Back to API List](https://koreai.mintlify.site/ai-for-service/apis/automation/api-list)

Retrieves engagement metrics for a specific app in a workspace over a chosen time period, including unique users, new users, returning users, and average user counts.

| Field | Value |
| - | - |
| **Method** | POST |
| **Endpoint** | `https://{{host}}/api/public/bot/{{streamId}}/v2/userEngagementTrend?aggregation_type={{aggregation_type}}&start_date={{start_date}}&end_date={{end_date}}&conversationType={{conversationType}}&conversationStatus={{conversationStatus}}&timeZoneOffset=Asia/Kolkata` |
| **Content Type** | `application/json` |
| **Authorization** | `auth: {{JWT}}` See [How to generate the JWT Token](https://koreai.mintlify.site/ai-for-service/apis/automation/api-introduction.md#generating-the-jwt-token). |
| **API Scope** | App Builder: User Engagement Trend; Admin Console: Not Applicable |

## Path Parameters

| Parameter | Required | Description |
| - | - | - |
| `host` | Required | Environment URL, for example, `https://platform.kore.ai` |
| `streamId` | Required | App ID or Stream ID. You can access it by navigating to **App Settings** → **App Profile** in the app. |

## Query Parameters

| Parameter | Description | Type |
| - | - | - |
| `aggregation_type` | Specifies the time-based aggregation level. Allowed values: `daily` and `hourly`. Defaults to `hourly`. | string, optional |
| `start_date` | Start date for retrieving analytics data in `YYYY-MM-DD` format. | string, required |
| `end_date` | End date for retrieving analytics data in `YYYY-MM-DD` format. | string, required |
| `conversationType` | Filters analytics data by conversation type. Allowed values: `All`, `Interactive`, `Non Interactive`. Defaults to `All`. | string, optional |
| `conversationStatus` | Filters analytics data by conversation status. Allowed values: `All`, `Active`, `Closed`. Defaults to `All`. | string, optional |
| `channels` | Filters analytics data by the specified channel. Defaults to `All`. | string, optional |
| `timeZoneOffset` | Time zone used to normalize and aggregate date and time values (for example, `Asia/Kolkata`). | string, optional |

## Sample Request

```json theme={null}
curl --location --request POST 'https://{{host}}/api/public/bot/{{streamId}}/v2/userEngagementTrend?aggregation_type={{aggregation_type}}&start_date={{start_date}}&end_date={{end_date}}&conversationType={{conversationType}}&conversationStatus={{conversationStatus}}&timeZoneOffset=Asia%2FKolkata' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}'
```

## Sample Response

**When `aggregation_type = Daily`:**

```json expandable=true theme={null}
{
    "summary": {
        "uniqueUsers": 2,
        "newUsers": 2,
        "returningUsers": 0,
        "avgUniqueUsersPerDay": 0.4,
        "avgNewUsersPerDay": 0.4,
        "avgReturningUsersPerDay": 0
    },
    "uniqueUsersTrend": {
        "dataPoints": [
            {
                "date": "Dec 01 2025",
                "users": 0
            },
            {
                "date": "Dec 03 2025",
                "users": 1
            }
        ]
    },
    "filters": {
        "start": "Dec 01 2025",
        "end": "Dec 05 2025",
        "conversationType": "all",
        "conversationStatus": "all",
        "aggregationType": "daily",
        "dataPointsCount": 5
    }
}
```

## Response Parameters

| Parameter | Description | Type |
| - | - | - |
| `summary` | Aggregated user metrics for the selected period. | Object |
| `summary.uniqueUsers` | Total number of unique users in the selected period. | Integer |
| `summary.newUsers` | Total number of new users in the selected period. | Integer |
| `summary.returningUsers` | Total number of returning users in the selected period. | Integer |
| `summary.avgUniqueUsersPerDay` | Average number of unique users per day for the selected period. | Number |
| `summary.avgNewUsersPerDay` | Average number of new users per day for the selected period. | Number |
| `summary.avgReturningUsersPerDay` | Average number of returning users per day for the selected period. | Number |
| `uniqueUsersTrend` | Trend data for unique users based on the selected aggregation type. | Object |
| `uniqueUsersTrend.dataPoints` | List of date-wise user engagement data points. | Array of Objects |
| `uniqueUsersTrend.dataPoints.date` | Date corresponding to the data point (formatted as `MMM DD YYYY`). | String |
| `uniqueUsersTrend.dataPoints.users` | Total count of unique users for the day. Displayed only when `aggregation_type` is `daily`. | Integer |
| `newUsersTrend` | Trend data for new users based on the selected aggregation type. | Object |
| `returningUsersTrend` | Trend data for returning users based on the selected aggregation type. | Object |
| `filters` | Metadata describing the filters applied to generate the response. | Object |
| `filters.start` | Start date of the applied filter range. | String |
| `filters.end` | End date of the applied filter range. | String |
| `filters.conversationType` | Conversation type filter applied. | String |
| `filters.conversationStatus` | Conversation status filter applied. | String |
| `filters.aggregationType` | Aggregation level applied to the data (`daily` or `hourly`). | String |
| `filters.dataPointsCount` | Total number of data points returned in the response. | Integer |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.