Sessions History API

Back to API List

Retrieves conversation sessions. Returns session metadata, user and bot identifiers, session duration, language, status, and other relevant metrics.

Field	Value
Method	POST
Endpoint	https://{{host}}/api/public/bot/{{BotID}}/getSessions?containmentType={{containmentType}} (or https://{{host}}/api/public/getSessions?containmentType={{containmentType}} for BAC)
Content Type	application/json
Authorization	auth: {{JWT}} See How to generate the JWT Token.
API Scope	App Builder: Bot Sessions; Admin Console: Bot Analytics > Bot Sessions

Header Parameters

Parameter	Description
host	Environment URL, for example, https://platform.kore.ai.
BotID	Bot ID or Stream ID. Access it from the General Settings page of the bot.

Query Parameters

Parameter	Required	Type	Description
containmentType	Optional	String	Filter results by session type: dropOff, selfService, or agent.

Sample Request

Without a body:

curl --location --request POST 'https://{{host}}/api/public/getSessions?containmentType={{containmentType}}' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json'

With a body:

curl --location --request POST 'https://{{host}}/api/public/getSessions?containmentType={{containmentType}}' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "skip": 0,
        "limit": 100,
        "dateFrom": "2020-02-11",
        "dateTo": "2020-02-12",
        "includeMeta": true
     }'

For a specific bot:

curl --location --request POST 'https://{{host}}/api/public/bot/{{BotId}}/getSessions?containmentType={{containmentType}}' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "skip": 0,
        "limit": 100,
        "dateFrom": "2020-02-11",
        "dateTo": "2020-02-12",
        "includeSiprecSessions": true
     }'

For specific session IDs:

curl --location --request POST 'https://{{host}}/api/public/bot/{{BotId}}/getSessions' \
     --header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "sessionId": ["6465cf6e4769ed4e822bxxxx","6465cf6e47Q9ed4e822bxxxx"]
     }'

For specific external call IDs:

curl --location POST 'https://{{host}}/api/public/bot/{{BotId}}/getSessions?callId={{callId}}' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
    "skip": 0,
    "limit": 100,
    "dateFrom": "2025-03-17",
    "dateTo": "2025-03-19",
    "includeMeta": true
}'

Request Body Parameters

Parameter	Required	Type	Description
userId	Optional	String	The user ID (email or enterprise-assigned unique ID).
skip/offset	Optional	Number	Number of messages to skip.
limit	Optional	Number	Number of messages per page. Sessions are returned in descending order of start time.
dateFrom	Optional	Date	Start date in yyyy-mm-dd or yyyy-mm-ddThh:mm:ss.msZ format. Defaults to 7 days before dateTo.
dateTo	Optional	Date	End date in yyyy-mm-dd or yyyy-mm-ddThh:mm:ss.msZ format. Defaults to today if neither date is provided.
tags	Optional	Object	Meta tags to filter conversations.
includeMeta	Optional	Boolean	Set to true for encrypted response. Default: False
sessionType	Optional	String	Filter by session type: non-interactive (bot messages without user input) or interactive (sessions with user messages).
sessionId	Optional		Array of up to 50 session IDs. If used, all other filters are ignored. Querying using sessionId returns sessionTags only for sessions from the last 14 days. To retrieve sessionTags for older sessions, use dateFrom and dateTo with a date range of less than 7 days.
includeSiprecSessions	Optional	Boolean	Specifies whether to include SIPREC sessions in the response. Set to true to include SIPREC sessions and false to exclude them.

When dateFrom or dateTo uses the YYYY-MM-DD format, the platform interprets the value as the start of that day (YYYY-MM-DDT00:00:00). To retrieve data for a full day, specify the complete timestamp or set dateTo to the following day. For example, use "dateFrom": "2026-07-20T00:00:00Z" with "dateTo": "2026-07-20T23:59:59Z" or "dateTo": "2026-07-21".

Response Body Parameters

Parameter	Type	Description
moreAvailable	Boolean	Indicates if more records are available for retrieval.
total	Number	The total count of available records.

Response sample

{
    "total": 2,
    "moreAvailable": true,
    "sessions": [
        {
            "sessionId": "67d97c8fd495b147d9c3xxxx",
            "botId": "st-89cf14ef-145e-5263-994e-5d757325xxxx",
            "channel": "korevg",
            "userId": "u-c3c0b243-becc-5cce-a845-f681a62dxxxx",
            "start_time": "2025-03-18T14:00:47.505Z",
            "end_time": "2025-03-18T14:01:37.518Z",
            "session_lang": [
                "en"
            ],
            "sessionType": "interactive",
            "isDeveloper": false,
            "sessionStatus": "closed",
            "tags": {
                "userTags": [],
                "sessionTags": [
                    {
                        "value": "1",
                        "name": "welcomeMessageTwilio"
                    },
                    {
                        "value": "+112*****89",
                        "name": "callerNumber"
                    },
                    {
                        "value": "1",
                        "name": "voiceAgentTransferStart"
                    },
                    {
                        "value": "1",
                        "name": "audioCodesCallDisconnect"
                    }
                ],
                "altText": []
            },
            "noOfMessagesExchanged": 4,
            "noOfTasksExecuted": 1,
            "containmentType": "agent"
        },
    ]
}