User Engagement Trend API - v2

Back to 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.
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

When aggregation_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