> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-content-gov.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Sessions History API
[Back to API List](/ai-for-service/apis/automation/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](/ai-for-service/apis/automation/api-introduction/#generating-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](/ai-for-service/app-settings/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:**
```yaml theme={null}
curl --location --request POST 'https://{{host}}/api/public/getSessions?containmentType={{containmentType}}' \
--header 'auth: {{JWT_TOKEN}}' \
--header 'Content-Type: application/json'
```
**With a body:**
```yaml theme={null}
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:**
```yaml theme={null}
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:**
```yaml theme={null}
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:**
```yaml theme={null}
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
```json expandable=true theme={null}
{
"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.