Sessions History API - Kore.ai Docs

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 identifier or Stream identifier. Access it from the App Profile page of the bot.

Query Parameters

Parameter	Required	Type	Description
`containmentType`	Optional	String	Filter results by session type: `dropOff`, `selfService`, or `agent`.
`callId`	Optional	String	A single external call ID to filter sessions details. For multiple call IDs, use the `callIds` array in the request body instead. Don’t send `callId` and `callIds` in the same request.

Sample Request

Without a body:

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

With a body:

curl --location --request POST 'https://{{host}}/api/public/getSessions?containmentType={{containmentType}}' \
     --header 'auth: {{JWT_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: {{JWT_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
        "skip": 0,
        "limit": 100,
        "dateFrom": "2020-02-11",
        "dateTo": "2020-02-12",
        "includeSiprecSessions": true,
        "callIds": ["call-id-001", "call-id-002"]
     }'

For specific session IDs:

curl --location --request POST 'https://{{host}}/api/public/bot/{{botId}}/getSessions' \
     --header 'auth: {{JWT_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: {{JWT_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	Integer	Number of messages to skip.
`limit`	Optional	Integer	Number of messages per page. Sessions are returned in descending order of start time.
`dateFrom`	Optional	String	Start date to fetch records in ISO 8601 format. Defaults to 7 days before `dateTo`. 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"`.
`dateTo`	Optional	String	End date to fetch records in ISO 8601 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	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

Field	Type	Description
`total`	Integer	Total number of sessions returned in the response.
`moreAvailable`	Boolean	Indicates whether additional sessions are available beyond the current response.
`sessions`	Array	List of session details.
`sessionId`	String	Unique identifier of the session.
`botId`	String	Unique identifier of the bot associated with the session.
`channel`	String	Channel through which the session was initiated.
`userId`	String	Unique identifier of the user associated with the session.
`start_time`	String	Date and time when the session started in ISO 8601 format.
`end_time`	String	Date and time when the session ended in ISO 8601 format.
`session_lang`	Array	Languages used during the session.
`sessionType`	String	Type of session, such as `interactive`.
`isDeveloper`	Boolean	Indicates whether the session was initiated by a developer.
`sessionStatus`	String	Current status of the session, such as `closed` or `active`.
`tags`	Object	Collection of tags associated with the session.
`userTags`	Array	User-defined tags associated with the session.
`sessionTags`	Array	Session-level tags associated with the session.
`value`	String	Value assigned to the session tag.
`name`	String	Name of the session tag.
`altText`	Array	Alternate text tags associated with the session.
`noOfMessagesExchanged`	Number	Total number of messages exchanged during the session.
`noOfTasksExecuted`	Number	Total number of tasks executed during the session.
`containmentType`	String	Indicates how the session was resolved, such as `bot`, `agent`, or `mixed`.

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"
        },
    ]
}

If callIds is provided as an empty array, the API behaves as if the callIds field were not present in the request payload.

​Header Parameters

​Query Parameters

​Sample Request

​Request Body Parameters

​Response Body Parameters

​Response sample

Header Parameters

Query Parameters

Sample Request

Request Body Parameters

Response Body Parameters

Response sample