---
title: "POST /bots/{botId}/analytics/sessions"
method: POST
path: "/bots/{botId}/analytics/sessions"
---

# POST /bots/{botId}/analytics/sessions

`POST /bots/{botId}/analytics/sessions`

Retrieves a list of metadata for individual user sessions with your bot. The `startDateTime` and `endDateTime` fields are required. These fields define a time range for which you want to retrieve results. Of the optional fields, you can organize the results in the following ways:

*   Use the `filters` field to filter the results and the `sortBy` field to specify the values by which to sort the results.
    
*   Use the `maxResults` field to limit the number of results to return in a single response and the `nextToken` field to return the next batch of results if the response does not return the full set of results.

## Path parameters

- `botId` string, required

## Request body

- object
  - `startDateTime` string, date-time, required — The date and time that marks the beginning of the range of time for which you want to see session analytics.
  - `endDateTime` string, date-time, required — The date and time that marks the end of the range of time for which you want to see session analytics.
  - `sortBy` object — An object specifying the measure and method by which to sort the session analytics data.
    - `name` 'ConversationStartTime' | 'NumberOfTurns' | 'Duration' — <p>The measure by which to sort the session analytics data.</p> <ul> <li> <p> <code>conversationStartTime</code> – The date and time when the conversation began. A conversation is defined as a unique combination of a <code>sessionId</code> and an <code>originatingRequestId</code>.</p> </li> <li> <p> <code>numberOfTurns</code> – The number of turns that the session took.</p> </li> <li> <p> <code>conversationDurationSeconds</code> – The duration of the conversation in seconds.</p> </li> </ul>
    - `order` 'Ascending' | 'Descending' — Specifies whether to sort the results in ascending or descending order.
  - `filters` AnalyticsSessionFilter[] — A list of objects, each of which describes a condition by which you want to filter the results.
    - `name` 'BotAliasId' | 'BotVersion' | 'LocaleId' | 'Modality' | 'Channel' | 'Duration' | 'ConversationEndState' | 'SessionId' | 'OriginatingRequestId' | 'IntentPath', required — <p>The category by which to filter the sessions. The descriptions for each option are as follows:</p> <ul> <li> <p> <code>BotAlias</code> – The name of the bot alias.</p> </li> <li> <p> <code>BotVersion</code> – The version of the bot.</p> </li> <li> <p> <code>LocaleId</code> – The locale of the bot.</p> </li> <li> <p> <code>Modality</code> – The modality of the session with the bot (audio, DTMF, or text).</p> </li> <li> <p> <code>Channel</code> – The channel that the bot is integrated with.</p> </li> <li> <p> <code>Duration</code> – The duration of the session.</p> </li> <li> <p> <code>conversationEndState</code> – The final state of the session.</p> </li> <li> <p> <code>SessionId</code> – The identifier of the session with the bot.</p> </li> <li> <p> <code>OriginatingRequestId</code> – The identifier of the first request in a session.</p> </li> <li> <p> <code>IntentPath</code> – The order of intents taken in a session.</p> </li> </ul>
    - `operator` 'EQ' | 'GT' | 'LT', required — <p>The operation by which to filter the category. The following operations are possible:</p> <ul> <li> <p> <code>CO</code> – Contains</p> </li> <li> <p> <code>EQ</code> – Equals</p> </li> <li> <p> <code>GT</code> – Greater than</p> </li> <li> <p> <code>LT</code> – Less than</p> </li> </ul> <p>The operators that each filter supports are listed below:</p> <ul> <li> <p> <code>BotAlias</code> – <code>EQ</code>.</p> </li> <li> <p> <code>BotVersion</code> – <code>EQ</code>.</p> </li> <li> <p> <code>LocaleId</code> – <code>EQ</code>.</p> </li> <li> <p> <code>Modality</code> – <code>EQ</code>.</p> </li> <li> <p> <code>Channel</code> – <code>EQ</code>.</p> </li> <li> <p> <code>Duration</code> – <code>EQ</code>, <code>GT</code>, <code>LT</code>.</p> </li> <li> <p> <code>conversationEndState</code> – <code>EQ</code>, <code>CO</code>.</p> </li> <li> <p> <code>SessionId</code> – <code>EQ</code>.</p> </li> <li> <p> <code>OriginatingRequestId</code> – <code>EQ</code>.</p> </li> <li> <p> <code>IntentPath</code> – <code>EQ</code>.</p> </li> </ul>
    - `values` AnalyticsFilterValue[], required — An array containing the values of the category by which to apply the operator to filter the results. You can provide multiple values if the operator is <code>EQ</code> or <code>CO</code>. If you provide multiple values, you filter for results that equal/contain any of the values. For example, if the <code>name</code>, <code>operator</code>, and <code>values</code> fields are <code>Modality</code>, <code>EQ</code>, and <code>[Speech, Text]</code>, the operation filters for results where the modality was either <code>Speech</code> or <code>Text</code>.
  - `maxResults` integer — The maximum number of results to return in each page of results. If there are fewer results than the maximum page size, only the actual number of results are returned.
  - `nextToken` string — <p>If the response from the ListSessionAnalyticsData operation contains more results than specified in the maxResults parameter, a token is returned in the response.</p> <p>Use the returned token in the nextToken parameter of a ListSessionAnalyticsData request to return the next page of results. For a complete set of results, call the ListSessionAnalyticsData operation until the nextToken returned in the response is null.</p>

## Response `200`

Success

- ListSessionAnalyticsDataResponse
  - `botId` string — The unique identifier of the bot that the sessions belong to.
  - `nextToken` string — <p>If the response from the ListSessionAnalyticsData operation contains more results than specified in the maxResults parameter, a token is returned in the response.</p> <p>Use the returned token in the nextToken parameter of a ListSessionAnalyticsData request to return the next page of results. For a complete set of results, call the ListSessionAnalyticsData operation until the nextToken returned in the response is null.</p>
  - `sessions` SessionSpecification[] — A list of objects, each of which contains information about a session with the bot.
    - `botAliasId` string — The identifier of the alias of the bot that the session was held with.
    - `botVersion` string — The version of the bot that the session was held with.
    - `localeId` string — The locale of the bot that the session was held with.
    - `channel` string — The channel that is integrated with the bot that the session was held with.
    - `sessionId` string — The identifier of the session.
    - `conversationStartTime` string, date-time — The date and time when the conversation began. A conversation is defined as a unique combination of a <code>sessionId</code> and an <code>originatingRequestId</code>.
    - `conversationEndTime` string, date-time — The date and time when the conversation ended. A conversation is defined as a unique combination of a <code>sessionId</code> and an <code>originatingRequestId</code>.
    - `conversationDurationSeconds` integer — The duration of the conversation in seconds. A conversation is defined as a unique combination of a <code>sessionId</code> and an <code>originatingRequestId</code>.
    - `conversationEndState` 'Success' | 'Failure' | 'Dropped' — The final state of the conversation. A conversation is defined as a unique combination of a <code>sessionId</code> and an <code>originatingRequestId</code>.
    - `mode` 'Speech' | 'Text' | 'DTMF' | 'MultiMode' — <p>The mode of the session. The possible values are as follows:</p> <ul> <li> <p> <code>Speech</code> – The session was spoken.</p> </li> <li> <p> <code>Text</code> – The session was written.</p> </li> <li> <p> <code>DTMF</code> – The session used a touch-tone keypad (Dual Tone Multi-Frequency).</p> </li> <li> <p> <code>MultiMode</code> – The session used multiple modes.</p> </li> </ul>
    - `numberOfTurns` integer — The number of turns that the session took.
    - `invokedIntentSamples` InvokedIntentSample[] — A list of objects containing the name of an intent that was invoked.
      - `intentName` string — The name of an intent that was invoked.
    - `originatingRequestId` string — The identifier of the first request in a session.

## Other responses

- `480` — ThrottlingException
- `481` — ValidationException
- `482` — PreconditionFailedException
- `483` — ServiceQuotaExceededException
- `484` — InternalServerException

---

[API](https://skmtc.net/aws/apis/lexv2-models.md) · [All operations](https://skmtc.net/aws/apis/lexv2-models/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/lexv2-models/versions/6997ba482d72/schema)