Skip to content

Get Analytics API

The Get Analytics API allows you to retrieve metrics data related to intent detection and task performance. The API provides information about various metrics, including Intents Found, Intents not Found, Unhandled Utterances, Failed Tasks, Successful Tasks, and Performance Logs.

Method POST
Endpoint https://{{host}}/api/public/bot/{{BotID}}/getAnalytics
Content Type application/json
Authorization auth: {{JWT}}

See How to generate the JWT Token.

API Scope
  • Bot Builder: Metrics
  • Admin Console: Not Applicable

Path Parameters

PARAMETER REQUIRED/OPTIONAL DESCRIPTION
host Required Environment URL, for example, https://platform.kore.ai
BotID Required Bot ID or Stream ID. You can access it from the General Settings page of the bot.

Sample Request

The following sample request shows how to retrieve unhandled utterance analytics data with specific filters. You can modify the type and filters parameters to retrieve different types of analytics data as needed.

curl --location --request POST 'https://platform.kore.ai/api/public/bot/st-xxxxxxd-xxxx-xxxx-xxxx-xxxxxxxxxx/getAnalytics' \
--header 'auth: {{YOUR_JWT_ACCESS_TOKEN}}' \
--header 'content-type: application/json' \
--data-raw '{
    "type": "unhandledutterance",
    "filters": {
        "from": "2022-09-11T17:25:09.698Z",
        "to": "2022-09-25T17:25:09.698Z",




        "channel": [
            "rtm"
        ],
        "isAmbiguous": false,
        "isDeveloper": false,
        "trained": false,
        "userId": [
            "u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
        ]




    },
    "sort":
        { "order": "asc",
          "by": "nodeName" },


    "limit": 50
}'

Request Body Parameters

PARAMETER REQUIRED/OPTIONAL TYPE DESCRIPTION
type Required String Indicates the type of metrics for which you can retrieve data:
  • successintent
  • failintent
  • successtask
  • failtask
  • performance
  • unhandledutterance
filters Required Object A set of filters to narrow down the analytics data.
filters.from Required String The start timestamp for the data retrieval.
filters.to Required String The end timestamp for the data retrieval.
filters.channel Optional Array of strings An array containing channel names to filter data by; the default channel is “rtm”.

Accepted channels are:

  • “skypeforbusiness”
  • “msteams”
  • “twitter”
  • “spark”
  • “rtm”
  • “facebook”
  • “slack”
  • “skype”
  • “kore”
  • “email”
  • “sms”
  • “facebook”
  • “ringcentral”
  • “jabber”
  • “yammer”
  • “alexa”
  • “twiliovoice”
  • “telegram”
  • “ivr”
  • “ivrVoice”
  • “smartassist”
  • “line”
  • “liveperson”
  • “googleactions”
  • “hangoutchat”
  • “mattermost”
  • “rcs”
filters.channel.channelUIds Optional Array of strings The end-user’s identity provided by the channel.
filters.isAmbiguous Optional Boolean Whether to include ambiguous intents or not – set to true or false.
filters.isDeveloper Optional Boolean Whether to include developer metrics – set to true or false.
filters.trained Optional Boolean Whether to include trained intents or not – set to true or false.
filter.taskId Optional Array of strings To filter based on the task IDs.
filters.userId Optional Array of strings To filter based on user IDs.
filters.tags Optional Object Meta tags to filter the records.

Usage example:

"tags": {

"and": [

{

"name": "user",

"values": ["uservalue"],

"type": "user"

},

{

"name": "message",

"values": ["mvalue"],

"type": "message"

}

]

}

sort Optional Object An object containing the sorting criteria to apply to the data being retrieved:
  • order (string, required): Sorting order, either “asc” for ascending or “desc” for descending.
  • by (string, required): The field/column by which the data should be sorted.

    Usage example:

    "sort":

    { "order": "<desc/asc>",

    "by": "<column name>" }

limit Required Number Indicates the number of records to be returned in the result set.
skip Required Number The number of records to be skipped from the result set.

Sample Response

{
    "moreAvailable": false,
    "result": [
        {
            "_id": "63xxxxxxxxxxxxxxxxx",
            "messageId": "ms-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
            "sessionId": "63xxxxxxxxxxxxxxx",
            "utterance": "aslfkj",
            "intent": "Mobile Enquiry",
            "userId": "u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
            "channelUId": "test@abc.xyz",
            "language": "en",
            "timestamp": "2022-09-24T08:24:39.840Z",
            "pinned": false,
            "channel": "rtm",
            "winningIntent": [],
            "isAmbiguous": false,
            "ambiguousIntents": [],
            "taskName": "Mobile Enquiry",
            "flow": [],
            "taskId": "dg-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
            "koralogstatusId": "f-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx-xxxxxxxxxxx",
            "customTags": {
                "userTags": [
                    {
                        "name": "Name",
                        "value": "John"
                    }
                ],
                "sessionTags": [],
                "messageTags": []
            },
            "NLAnalysis": {
                "result": "unhandledUtterance",
                "messageStoreId": "ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
                "channelId": "st-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx:u-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx:rtm",
                "bot": "Channel Check",
                "botid": "st-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
                "skipConversation": true,
                "task": "Mobile Enquiry",
                "botLanguage": "en-US",
                "nluLanguage": "en-US",
                "taskId": "dg-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
                "fields": {},
                "logSequenceId": "f-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx-xxxxxxxxxx",
                "intentStatus": "published",
                "subType": "dialog",
                "channelInfo": "st-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:u-xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:rtm",
                "input": [
                    "aslfkj"
                ],
                "taskContextId": "dcx-xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
                "NLAnalysis": {
                    "intentRescoring": true,
                    "isPreferDefinitiveMatch": true,
                    "scoringModel": "original",
                    "toneAnalysis": {},
                    "nlProcessing": {
                        "originalInput": "aslfkj",
                        "spellCorrectedInput": null,
                        "canonical": "Aslak",
                        "wordAnalysis": [
                            {
                                "index": 1,
                                "word": "Aslak",
                                "ignored": false,
                                "pos": "Noun_proper_singular ",
                                "role": "MAINSUBJECT ",
                                "original": "aslfkj",
                                "processedWord": "Aslak"
                            }
                        ]
                    },
                    "ml": {
                        "intentModel": "bot level intent model",
                        "eliminated": [
                            {
                                "task": "Book Appointment",
                                "state": "published",
                                "score": 0.017055602351504544,
                                "scoringCriteria": "Probabilistic score",
                                "matchType": "unlikely"
                            },
                            {
                                "task": "Transfer Money",
                                "state": "published",
                                "score": 0.011911144983740555,
                                "scoringCriteria": "Probabilistic score",
                                "matchType": "unlikely"
                            },
                            {
                                "task": "Show Balance",
                                "state": "published",
                                "score": 0.009209086809082547,
                                "scoringCriteria": "Probabilistic score",
                                "matchType": "unlikely"
                            }
                        ],
                        "namedEntityRecognition": []
                    },
                    "faq": {
                        "demystify": {
                            "lemmatizer_used": "PATTERN",
                            "normalizedQuery": "aslfkj",
                            "OntologyTraits": [],
                            "failed_questions": {},
                            "SelectedPathCount": 3,
                            "ExtractedEntities": [],
                            "ContextEntities": [],
                            "PreConditionNodes": [],
                            "filtered_questions": {
                                "score": [],
                                "traits": []
                            }
                        }
                    }
                },
                "language": "en",
                "channel": "rtm",
                "userId": "u-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
                "time": "2022-09-24T08:24:39.808Z",
                "channelclient": "botbuilder",
                "_id": "f-121d2486-xxxx-xxxx-xxxx-xxxxxxxxxx-xxxxxxxxxx",
                "resourceid": "korastatuslogs",
                "entityOrgId": "o-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
                "iv": "VP47awbZ8JRCoqFtgPx7fA==",
                "cek": {
                    "header": {
                        "alg": "dir",
                        "enc": "aes-256-cbc",
                        "kid": "k-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"
                    }
                },
                "ire": true
            },
            "nodeName": "Entity_color",
            "promptType": "entity"
        },
        {
            "_id": "63xxxxxxxxxxxx",
            "messageId": "ms-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
            "sessionId": "63xxxxxxxxxxxxxxxxx",
            "utterance": "alskd",
            "intent": "Mobile Enquiry",
            "userId": "u-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
            "channelUId": "ramakrishnakoretest@getnada.com",
            "language": "en",
            "timestamp": "2022-09-24T08:24:50.257Z",
            "pinned": false,
            "channel": "rtm",
            "winningIntent": [],
            "isAmbiguous": false,
            "ambiguousIntents": [],
            "taskName": "Mobile Enquiry",
            "flow": [],
            "taskId": "dg-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
            "koralogstatusId": "f-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx-xxxxxxx",
            "customTags": {
                "userTags": [
                    {
                        "name": "Name",
                        "value": "Krishna"
                    }
                ],
                "sessionTags": [],
                "messageTags": []
            },
            "NLAnalysis": {
                "result": "unhandledUtterance",
                "messageStoreId": "ms-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
                "channelId": "st-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx:u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:rtm",
                "bot": "Channel Check",
                "botid": "st-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
                "skipConversation": true,
                "task": "Mobile Enquiry",
                "botLanguage": "en-US",
                "nluLanguage": "en-US",
                "taskId": "dg-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
                "fields": {},
                "logSequenceId": "f-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx-xxxxxxx",
                "intentStatus": "published",
                "subType": "dialog",
                "channelInfo": "st-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx:u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx:rtm",
                "input": [
                    "alskd"
                ],
                "taskContextId": "dcx-b3e58798-ed3b-5f3d-9894-2e26758001eb",
                "NLAnalysis": {
                    "intentRescoring": true,
                    "isPreferDefinitiveMatch": true,
                    "scoringModel": "original",
                    "toneAnalysis": {},
                    "nlProcessing": {
                        "originalInput": "alskd",
                        "spellCorrectedInput": null,
                        "canonical": "alskd",
                        "wordAnalysis": [
                            {
                                "index": 1,
                                "word": "unknown-word",
                                "ignored": false,
                                "pos": "Noun_infinitive Noun_singular Verb_infinitive Verb_present Adjective_normal Adverb ",
                                "original": "alskd",
                                "processedWord": "alskd"
                            }
                        ]
                    },
                    "ml": {
                        "intentModel": "bot level intent model",
                        "eliminated": [
                            {
                                "task": "Book Appointment",
                                "state": "published",
                                "score": 0.017055602351504544,
                                "scoringCriteria": "Probabilistic score",
                                "matchType": "unlikely"
                            },
                            {
                                "task": "Transfer Money",
                                "state": "published",
                                "score": 0.011911144983740555,
                                "scoringCriteria": "Probabilistic score",
                                "matchType": "unlikely"
                            },
                            {
                                "task": "Show Balance",
                                "state": "published",
                                "score": 0.009209086809082547,
                                "scoringCriteria": "Probabilistic score",
                                "matchType": "unlikely"
                            }
                        ],
                        "namedEntityRecognition": []
                    },
                    "faq": {
                        "demystify": {
                            "lemmatizer_used": "PATTERN",
                            "normalizedQuery": "alskd",
                            "OntologyTraits": [],
                            "failed_questions": {},
                            "SelectedPathCount": 3,
                            "ExtractedEntities": [],
                            "ContextEntities": [],
                            "PreConditionNodes": [],
                            "filtered_questions": {
                                "score": [],
                                "traits": []
                            }
                        }
                    }
                },
                "language": "en",
                "channel": "rtm",
                "userId": "u-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
                "time": "2022-09-24T08:24:50.226Z",
                "channelclient": "botbuilder",
                "_id": "f-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx-xxxxxxxx",
                "resourceid": "korastatuslogs",
                "entityOrgId": "o-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
                "iv": "+Kl5i6AAFJp0g3NkExn+Og==",
                "cek": {
                    "header": {
                        "alg": "dir",
                        "enc": "aes-256-cbc",
                        "kid": "k-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx"
                    }
                },
                "ire": true
            },
            "nodeName": "Entity_capacity",
            "promptType": "entity"
        }
    ],
    "totalCount": 2
}

Response Body Parameters

PARAMETER TYPE DESCRIPTION
moreAvailable Boolean Indicates if the API has returned all the records or if more are available, based on the pagination criteria.

True if more records are available. False if there are no more records to be retrieved.

result Array of objects Contains complete information about the metrics.
id String The unique identifier for the record.
messagesId String The unique identifier for the message record.
sessionId String The unique identifier for the session.
utterance String The user utterance/input.
intent String The identified intent for the user’s utterance/input.
userId String The unique identifier for the user.
channelUId String The end-user’s identity provided by the channel. It can be the user’s email ID or enterprise-assigned unique ID.
language String The language in which the conversation happened with the bot.
timestamp String The response date is converted into timestamp format.
pinned Boolean Indicates whether the message is pinned – true or false.
channel String Name of the channel through which the conversation occurred.
winningIntent Array An array containing the winning intent(s) for the utterance.
isAmbiguous Boolean Indicates whether the intent is ambiguous – true or false.
ambiguousIntents Array An array of ambiguous intents, if applicable.
taskName String The name of the task associated with the conversation.
nodeName String The node name. This parameter is retrieved only for the Performance metric.
type String The type of the node. This parameter is retrieved only for the Performance metric.
status String The status of the task. This parameter is retrieved only for the Performance metric.
statusCode String The status code of the task. This parameter is retrieved only for the Performance metric.
responseTime String The response time for the task. This parameter is retrieved only for the Performance metric.
flow Array An array of task flows.
taskId String The unique identifier for the task.
koralogstatusId String The unique identifier for the koralog status.
customTags Object Custom tags added to the user’s profile.
customTags.userTags Array User tags added to the user’s profile information.
userTags.name String Tag’s name.
userTags.value String Tag’s value.
customTags.sessionTags Array Custom tags added to the conversation session.
customTags.messagesTags Array Meta tags to filter the conversations.
NLAnalysis Object Contains natural language analysis results, including intent recognition and other natural language processing details.

The ‘NLAnalysis’ object includes multiple sub-objects such as ‘intentRescoring’, ‘nlProcessing’, ‘ml’ (machine learning analysis), ‘fm’ (fundamental meaning analysis), ‘faq’ (frequently asked questions analysis), and finalResolver. Each of these sub-objects contains information related to the analysis process, such as linguistic analysis, intent recognition, and the elimination of unlikely intents, etc.

NLAnalysis.debugTitle String The metric type in the NL Analysis. Possible values are:
  • Intent Match Successful
  • Intent Match Failed
  • Intent Failed/Abandoned
  • Intent Completed Successfully
  • Unhandled Utterances
  • Performance
NLAnalysis.result String The result of the NL analysis. For example, the result can be an unhandled utterance or a failed task.
NLAnalysis.messageStoreId String A unique identifier for the message stored in the system.
NLAnalysis.channelId String The identifier for the channel where the conversation took place.
NLAnalysis.bot String The name of the bot that handled the conversation.
NLAnalysis.botid String The unique identifier for the bot.
NLAnalysis.skipConversation Boolean If set to true, skips the conversation record. If false, do not skip the conversation.
NLAnalysis.task String The name of the task associated with the conversation.
NLAnalysis.botLanguage String The language used by the bot.
NLAnalysis.nluLanguage String The language in which the NLP training happened for that particular bot language.
NLAnalysis.taskId String The unique identifier for the task associated with the conversation.
NLAnalysis.isDeveloper Boolean Whether the session was initiated by a developer – true or false.
NLAnalysis.reason Object The NL analysis reason object.
NLAnalysis.reason.cause String The cause for NL analysis failure. For example, the script node failure.
NLAnalysis.reason.causeId String The NL analysis cause id.
NLAnalysis.fields String The fields; Contains additional fields associated with the interaction.
NLAnalysis.logSequenceId String The unique log sequence identifier.
NLAnalysis.intentStatus String The status of the intent.
NLAnalysis.subType String The task subtype. For example, a dialog.
NLAnalysis.channelInfo String The bot channel information.
NLAnalysis.input Array An array containing the user’s input.
NLAnalysis.taskContextId String The unique task context identifier.
NLAnalysis.intentRescoring Boolean Indicates whether intent rescoring was enabled – true or false. (true means the system may reevaluate and rescore intents during the processing of the user’s input.)
NLAnalysis.isPreferDefinitiveMatch Boolean Indicates whether the system prefers a definitive match when recognizing intents – true or false.
NLAnalysis.scoringModel String The scoring model used for intent recognition. Possible value – original.
NLAnalysis.toneAnalysis Object The toneAnalysis object; Contains the tone analysis of the task. Learn more.
NLAnalysis.nlProcessing Object The nlProcessing object; Contains information about the linguistic analysis and natural language processing of the user’s input.
NLAnalysis.nlProcessing.originalInput String The original user input.
NLAnalysis.nlProcessing.spellCorrectedInput String If spelling correction is applied, it would contain the corrected user input. (Null indicates no spelling correction applied.)
NLAnalysis.nlProcessing.canonical String The canonical representation of the input; typically represents a normalized or recognized form of the user’s input.
NLAnalysis.nlProcessing.wordAnalysis Array An array of objects, each containing a detailed analysis of individual words in the user’s input.
NLAnalysis.nlProcessing.wordAnalysis.index Number The position of the word in the input.
NLAnalysis.nlProcessing.wordAnalysis.word String The recognized/analyzed word.
NLAnalysis.nlProcessing.wordAnalysis.ignored Boolean Indicates whether the word was ignored in the analysis – true or false.
NLAnalysis.nlProcessing.wordAnalysis.pos String Part-of-speech tagging for the word.
NLAnalysis.nlProcessing.wordAnalysis.role String The role or function of the word in the context.
NLAnalysis.nlProcessing.wordAnalysis.original String The original word.
NLAnalysis.nlProcessing.wordAnalysis.processedWord String The processed word.
NLAnalysis.ml Object The ml object; Contains information related to machine learning analysis, including intent recognition and elimination of unlikely intents. (Most of the parameters/values returned by the object are used internally.)
NLAnalysis.fm Object The fm object; Contains information related to fundamental meaning analysis, provides insights into the scoring, matching, and elimination of tasks, etc. (Most of the parameters/values returned by the object are used internally.)
NLAnalysis.faq Object The faq object; Contains detailed information about the analysis of user input related to faq. (Most of the parameters/values returned by the object are used internally.)
NLAnalysis.finalResolver Object The finalResolver object; Contains information related to the final resolution process and the determination of the response or action to be taken based on the user’s input. (Most of the parameters/values returned by the object are used internally.)
totalCount Number The total number of records identified as per the API request parameters.