> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions History API

[Back to API List](https://koreai.mintlify.site/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](https://koreai.mintlify.site/ai-for-service/apis/automation/api-introduction.md#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](https://koreai.mintlify.site/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. |

> [!NOTE]
>
> 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"
        },
    ]
}
```

> [!NOTE]
>
> If `callIds` is provided as an empty array, the API behaves as if the `callIds` field were not present in the request payload.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.