OData Analytics Endpoint
Cognigy.AI exposes a OData v4 analytics endpoint to retrieve analytics records and conversations. OData, the Best Way to REST is a powerful API framework, see more at OData.org. The OData Endpoint allows you to retrieve all raw data out of Cognigy. It has all your enterprise analytics needs covered, make fine grained queries in your spreadsheets or build rich dashboards for your bots with your favorite BI tool.
Usage and Authentication
You can connect to the OData endpoint using your API Key by connecting to respective OData URL on your server.
An OData URL is combined of the service root, the collection and api key parameter as follows:
https://<hostname>/<collection>?apikey=YOURAPIKEY
For example, on our demo server, the OData endpoint URL for the Analytics Records Collection is https://odata-demo.cognigy.ai/Records?apikey=YOURAPIKEY (where YOURAPIKEY must be replaced with your respective API Key). For On-Prem installations please replace the odata-demo.cognigy.ai hostname with the hostname configured for your local installation.
Excel/Power BI
When using PowerBI or Excel, you might be asked to authenticate. Simply choose
anonymous authentication.
We offer two OData Collection endpoints
- Analytics Records (
/Records) - Conversations (
/Conversations)
Caching
All OData requests are cached for 1 hour. Executing the same request within 1 hour will result in you retrieving the previously cached version.
Querying
The endpoint supports following the OData Query Language operators:
- $filter
- $skip
- $top
- $orderby
- $count
- $select
Example Queries
https://odata-demo.cognigy.ai/Records/$count?apikey=YOURAPIKEY
Return total count of Records
https://odata-demo.cognigy.ai/Records?apikey=YOURAPIKEY
Return all Records for the given APIKey
https://odata-demo.cognigy.ai/Records/?$top=10&apikey=YOURAPIKEY
Return the first 10 records
https://odata-demo.cognigy.ai/Records/?$filter=executionTime lt 50&$top=5&$orderby=executionTime&apikey=YOURAPIKEY
Return the top 5 records where the executionTime is lower than 50ms, ordered by executionTime
Reference documentation
For a full reference please refer to the extensive collection of resources at OData.org and the Oasis OData URL Convention Documentation.
Caching
All OData requests are cached for 10 minutes. Making more than one request within 10 minutes will result in you retrieving the previously cached version.
Data Management
You control and manage the data available in the OData Endpoint via the data producing Endpoint settings. See Data Management for more details:
-
If you disable Collect Analytics no analytics data will be logged from the endpoint and available in OData
-
If you enable Mask Sensitive Analytics the inputText and inputData fields will be masked.
Furthermore, you can control analytics logging behavior inside a Flow using Blind Mode nodes that will disable or mask analytics data available in OData according to your node settings.
Analytics Records Collection
Each time a contact interacts with one of your Flows, Cognigy stores detailed analytics logs about the interaction. Each interaction is exposed in the analytics endpoint as a Record.
The endpoint is https://odata-demo.cognigy.ai/Records?apikey=YOURAPIKEY.
When retrieving the Records, the endpoint will return the following fields.
| Field Name | Description | Type | Example |
|---|---|---|---|
| _id | Unique analytics record ID | String | 5a91d194fde28b0011ce2423 |
| organisation | Name of your organisation | String | cognigy |
| projectId | Project ID | String | 5a91d194fde28b0011ce2422 |
| flowParentId | ParentId of the Flow | String | 5e33b160e6236da3aa54221461a53f04 |
| ip | The IP address the request originated from | String | 78.143.45.111 |
| contactId | ID of the connecting user | String | myContactID |
| sessionId | Session ID | String | 5a91d194fde28b0011ce2425 |
| inputId | Unique input ID | String | 5a91d194fde28b0011ce2424 |
| inputText | The input text | String | Hello World! |
| inputData | The input data object as a string | String | {"key":"value"} |
| state | State of the Flow at input | String | default |
| mode | Mode of the input | String | TextOnly |
| userType | Type of the connecting user. Either "external" for external user or "admin" for admin user | String | external |
| channel | Channel the input came through | String | |
| flowVersion | Version of the Flow | Number | 1 |
| flowLanguage | Language of the Flow | String | en-EN |
| intent | Found intent (can be blank) | String | orderFood |
| intentFlow | The Parent ID of the Flow in which the intent was found (can be blank) | String | 5e33b160e6236da3aa54221461a53f04 |
| completedGoalsList | List of completed goals in this session | String | orderedFood |
| foundSlots | Found slot tags | String | DATE |
| foundSlotDetails | Found slot tags with details | String | DATE[2018-2-25T12:32:32.000] |
| understood | Whether any slots or intents were found | Boolean | true |
| timestamp | DateTime of the input | DateTime | 2018-2-25T12:32:32.000Z |
| executionTime | Time it took to execute the Flow in ms | Number | 32 |
| execution | The execution count | Number | 3 |
It also returns three custom fields that you can set within your Flow. You can define the content in a Code Node. The fields are called custom1, custom2 and custom3, and the value of the fields can be any string value, e.g. a stringified object.
Max length of custom fields
You can store maximum 500 characters as the value of each of the custom fields
Conversations Collection
The Conversations collection offers a log of all conversations, including the bot or handover agent responses.
| Field Name | Description | Type | Example |
|---|---|---|---|
| _id | Unique analytics record ID | String | 5a91d194fde28b0011ce2423 |
| inputId | Unique input ID | String | 5a91d194fde28b0011ce2424 |
| sessionId | Session ID | String | 5a91d194fde28b0011ce2425 |
| contactId | ID of the connecting user | String | myContactID |
| organisation | Name of your organisation | String | cognigy |
| inputText | The input text | String | Hello World! |
| inputData | The input data object as a string | String | {"key":"value"} |
| type | Whether the message is an input or output of the Flow | String | "input" or "output" |
| source | The source of the message | String | "user" or "bot" or "agent" or "suggestion" |
| timestamp | DateTime of the input | DateTime | 2018-2-25T12:32:32.000Z |
| flowName | Name of the Flow | String | MainFlow |
| flowParentId | ParentId of the Flow | String | 5e33b160e6236da3aa54221461a53f04 |
| channel | Channel the input came through | String | |
| inHandoverRequest | Flag whether the conversation is in a Handover request | Boolean | false |
| inHandoverConversation | Flag whether the conversation is in a Handover conversation | Boolean | true |
| outputId | Output ID | String | f514b7b2-7dc0-4e75-be62-a53fed5b2bb7 |
Integrations
Excel
When connecting from Microsoft Excel 2016, you must use the PowerQuery feature, which can be found under Data > Get & Transform > New Query > From Other Sources > From OData Feed. This will connect to our OData v4 feed.
PowerBI
Please follow the instructions in the Power BI documentation.
Tableau
Please find instructions on how to connect an OData Feed in Tableau here.
OData Consumer Ecosystem
For a full list of available OData Consumer options please follow the link to Consumers on OData.org.
Client Libraries in .NET, Java, JavaScript, C++ and other platforms
For a full list of available OData Libraries please see the latest directory of available libraries on OData.org.
Updated almost 3 years ago