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

# User Engagement Trend API - v2

<Badge icon="arrow-left" color="gray">[Back to API List](/ai-for-service/apis/automation/api-list)</Badge>

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](/ai-for-service/apis/automation/api-introduction#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 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          |