| 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. |
| 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
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
Whenaggregation_type = Daily:
{
"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 |