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}}
|
| API Scope |
|
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| host | Required | Environment URL, for example, https://bots.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://bots.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 | Type | Description |
|---|---|---|
| type | string, required | Indicates the type of metrics for which you can retrieve data:
|
| filters | object, required | A set of filters to narrow down the analytics data. |
| filters.from | string, required | The start timestamp for the data retrieval. |
| filters.to | string, required | The end timestamp for the data retrieval. |
| filters.channel | array of strings, optional | An array containing channel names to filter data by; the default channel is “rtm”.
Accepted channels are:
|
| filters.channel.channelUIds | array of strings, optional | The end-user’s identity provided by the channel.
Note: For “ivr” channel, it’s a combination of |
| filters.isAmbiguous | boolean, optional | Whether to include ambiguous intents or not – set to true or false. |
| filters.isDeveloper | boolean, optional | Whether to include developer metrics – set to true or false. |
| filters.trained | boolean, optional | Whether to include trained intents or not – set to true or false. |
| filter.taskId | array of strings, optional | To filter based on the task IDs. |
| filters.userId | array of strings, optional | To filter based on user IDs. |
| filters.tags | object, optional | Meta tags to filter the records. Usage example: "tags": {
"and": [
{
"name": "user",
"values": ["uservalue"],
"type": "user"
},
{
"name": "message",
"values": ["mvalue"],
"type": "message"
}
]
}
|
| sort | object, optional | An object containing the sorting criteria to apply to the data being retrieved:
Usage example: "sort":
{ "order": "<desc/asc>",
"by": "<column name>" }
|
| limit | integer, required | Indicates the number of records to be returned in the result set. |
| skip | integer, required | 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 | DESCRIPTION |
| moreAvailable | 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 | Contains complete information about the metrics. |
| id | The unique identifier for the record. |
| messagesId | The unique identifier for the message record. |
| sessionId | The unique identifier for the session. |
| utterance | The user utterance/input. |
| intent | The identified intent for the user’s utterance/input. |
| userId | The unique identifier for the user. |
| channelUId | The end-user’s identity provided by the channel. It can be the user’s email ID or enterprise-assigned unique ID. |
| language | The language in which the conversation happened with the bot. |
| timestamp | The response date is converted into timestamp format. |
| pinned | Indicates whether the message is pinned – true or false. |
| channel | Name of the channel through which the conversation occurred. |
| winningIntent | An array containing the winning intent(s) for the utterance. |
| isAmbiguous | Indicates whether the intent is ambiguous – true or false. |
| ambiguousIntents | An array of ambiguous intents, if applicable. |
| taskName | The name of the task associated with the conversation. |
| nodeName | The node name. This parameter is retrieved only for the Performance metric. |
| type | The type of the node. This parameter is retrieved only for the Performance metric. |
| status | The status of the task. This parameter is retrieved only for the Performance metric. |
| statusCode | The status code of the task. This parameter is retrieved only for the Performance metric. |
| responseTime | The response time for the task. This parameter is retrieved only for the Performance metric. |
| flow | An array of task flows. |
| taskId | The unique identifier for the task. |
| koralogstatusId | The unique identifier for the koralog status. |
| customTags | Custom tags added to the user’s profile. |
| customTags.userTags | User tags added to the user’s profile information. |
| userTags.name | Tag’s name. |
| userTags.value | Tag’s value. |
| customTags.sessionTags | Custom tags added to the conversation session. |
| customTags.messagesTags | Meta tags to filter the conversations. |
| NLAnalysis | 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 | The metric type in the NL Analysis. Possible values are:
|
| NLAnalysis.result | The result of the NL analysis. For example, the result can be an unhandled utterance or a failed task. |
| NLAnalysis.messageStoreId | A unique identifier for the message stored in the system. |
| NLAnalysis.channelId | The identifier for the channel where the conversation took place. |
| NLAnalysis.bot | The name of the bot that handled the conversation. |
| NLAnalysis.botid | The unique identifier for the bot. |
| NLAnalysis.skipConversation | If set to true, skips the conversation record. If false, do not skip the conversation. |
| NLAnalysis.task | The name of the task associated with the conversation. |
| NLAnalysis.botLanguage | The language used by the bot. |
| NLAnalysis.nluLanguage | The language in which the NLP training happened for that particular bot language. |
| NLAnalysis.taskId | The unique identifier for the task associated with the conversation. |
| NLAnalysis.isDeveloper | Whether the session was initiated by a developer – true or false. |
| NLAnalysis.reason | The NL analysis reason object. |
| NLAnalysis.reason.cause | The cause for NL analysis failure. For example, the script node failure. |
| NLAnalysis.reason.causeId | The NL analysis cause id. |
| NLAnalysis.fields | The fields; Contains additional fields associated with the interaction. |
| NLAnalysis.logSequenceId | The unique log sequence identifier. |
| NLAnalysis.intentStatus | The status of the intent. |
| NLAnalysis.subType | The task subtype. For example, a dialog. |
| NLAnalysis.channelInfo | The bot channel information. |
| NLAnalysis.input | An array containing the user’s input. |
| NLAnalysis.taskContextId | The unique task context identifier. |
| NLAnalysis.intentRescoring | 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 | Indicates whether the system prefers a definitive match when recognizing intents – true or false. |
| NLAnalysis.scoringModel | The scoring model used for intent recognition. Possible value – original. |
| NLAnalysis.toneAnalysis | The toneAnalysis object; Contains the tone analysis of the task. Learn more. |
| NLAnalysis.nlProcessing | The nlProcessing object; Contains information about the linguistic analysis and natural language processing of the user’s input. |
| NLAnalysis.nlProcessing.originalInput | The original user input. |
| NLAnalysis.nlProcessing.spellCorrectedInput | If spelling correction is applied, it would contain the corrected user input. (Null indicates no spelling correction applied.) |
| NLAnalysis.nlProcessing.canonical | The canonical representation of the input; typically represents a normalized or recognized form of the user’s input. |
| NLAnalysis.nlProcessing.wordAnalysis | An array of objects, each containing a detailed analysis of individual words in the user’s input. |
| NLAnalysis.nlProcessing.wordAnalysis.index | The position of the word in the input. |
| NLAnalysis.nlProcessing.wordAnalysis.word | The recognized/analyzed word. |
| NLAnalysis.nlProcessing.wordAnalysis.ignored | Indicates whether the word was ignored in the analysis – true or false. |
| NLAnalysis.nlProcessing.wordAnalysis.pos | Part-of-speech tagging for the word. |
| NLAnalysis.nlProcessing.wordAnalysis.role | The role or function of the word in the context. |
| NLAnalysis.nlProcessing.wordAnalysis.original | The original word. |
| NLAnalysis.nlProcessing.wordAnalysis.processedWord | The processed word. |
| NLAnalysis.ml | 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 | 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 | 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 | 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 | The total number of records identified as per the API request parameters. |