> ## 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

<Badge icon="arrow-left" color="gray">[Back to API List](/ai-for-service/apis/automation/api-list)</Badge>

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 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:**

```json theme={null}
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:**

```json theme={null}
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:**

```json theme={null}
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",
        "includeMeta": true
     }'
```

**For specific session IDs:**

```json theme={null}
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:**

```bash theme={null}
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. |

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