Skip to content

Cognigy.AI: OData Analytics Endpoint

OData (Open Data Protocol) is a standard for building and using RESTful APIs. It simplifies data access for web clients by providing a consistent way to describe data models and perform CRUD operations (Create, Read, Update, Delete) using standard HTTP methods and URLs.

Based on OData protocol version 4, Cognigy.AI offers an OData Analytics endpoint to retrieve raw data from Cognigy.AI using GET requests. This endpoint meets all your enterprise analytics needs, enabling you to make fine-grained queries in your spreadsheets or build rich dashboards for AI Agents with your favorite data visualization tool.

Watch this video to get a quick overview of what the OData Analytics endpoint is, how it works, and in which scenarios you can use it:

To analyze your AI Agent's performance, you can use the built-in Insights dashboards as an alternative to OData or in addition to it.

Restrictions

  • The Cognigy OData Endpoint supports only OData protocol version 4.
  • The Cognigy.AI OData endpoint only supports GET requests and does not support any other request types, such as PATCH, DELETE, or POST.
  • The data retrieved through the Cognigy.AI OData endpoint is not updated in real time and may not reflect current conditions or changes.

Data Protection

You can control data available through the OData endpoint at both the Endpoint and Flow levels:

  • Endpoint. Go to the Data Protection & Analytics section within the Endpoint, which manages data associated with your connections to channels such as webchat, Slack, and WhatsApp.
    • If you disable the Collect Analytics setting, no analytics data will be logged or available in OData.
    • If you enable the Mask Sensitive Analytics setting, the inputText and inputData fields will be masked.
  • Node. Add a Blind Mode Node to your Flow. This Node disables or masks analytics data available in the OData Endpoint.

Supported Versions

Cognigy.AI version Cognigy.AI OData Endpoint version
4.48 and later 2.3
4.31-4.47 2.0–2.3
4.30 and earlier 2.0–2.2

OData Endpoint Access

The OData endpoint is located on a different domain than your Cognigy User Interface domain:

Authentication

To connect to the OData endpoint, you need to have either odata or admin global role and an API Key.

OData Endpoint URL format:

https://<odata-domain>/<api-version>/<collection>?apikey=<your-api-key>, where

  • odata domain — the base domain of the OData service. It is the root URL where your OData service is hosted.
  • api-version — the version of the API you are interacting with. Currently, Cognigy.AI supports v2.3.
  • collection — a specific collection within the OData service you want to access. A collection is similar to a database table or a set of entities.
  • your-api-key — an API key that provides authentication and authorization for accessing the API. You need to get this key from your profile.

OData Endpoint URL example:

https://odata-trial.cognigy.ai/v2.3/Analytics?apikey=123abc, where

  • odata-trial.cognigy.ai — the Cognigy.AI OData base domain.
  • v2.3 — the API version of the Cognigy.AI OData endpoint.
  • Analytics — the Analytics data collection you're trying to access within Cognigy.AI.
  • 123abc — your unique API key.

Authentication for Microsoft Excel and Power BI

When using Microsoft Excel and Power BI, you might be prompted to authenticate. In this case, select Anonymous Authentication.

System Query Options

The OData Analytics Endpoint supports the following OData system query options:

  • $filter
  • $skip
  • $top
  • $orderby
  • $select
  • $count1

Examples

The tables contain examples of requests using System Query Options. Select the OData endpoint version compatible with your Cognigy.AI version.

Request Description OData 2.3 Request
Returns total count of Analytics records (not supported in Microsoft Excel or Power BI). https://odata-trial.cognigy.ai/v2.3/Analytics/$count?apikey=<your-api-key>
Returns all Analytics records for the given API Key. https://odata-trial.cognigy.ai/v2.3/Analytics?apikey=<your-api-key>
Returns the first 10 Analytics records. https://odata-trial.cognigy.ai/v2.3/Analytics/?$top=10&apikey=<your-api-key>
Returns the top 5 Analytics records where executionTime is less than 50ms, ordered by executionTime. https://odata-trial.cognigy.ai/v2.3/Analytics/?$filter=executionTime lt 50&$top=5&$orderby=executionTime&apikey=<your-api-key>
Returns all Analytics records for a specific Cognigy.AI Project filtered by projectId https://odata-trial.cognigy.ai/v2.3/Analytics/?$filter=projectId eq '<project-id>'&apikey=<your-api-key>
Returns Project IDs and Session IDs for a specific Cognigy.AI project. The request filters the data based on the projectId field and selects only the projectId and sessionId for each matching entry. https://odata-trial.cognigy.ai/v2.3/Analytics/?$filter=projectId eq '<project-id>'&$select=projectId,sessionId&apikey=<your-api-key>
Returns all Analytics records between two dates, for example, 1st Jan 2021 and 1st July 2021. https://odata-trial.cognigy.ai/v2.3/Analytics/?$filter=timestamp gt 2021-01-01T00:00:00.000Z and timestamp lt 2021-07-01T00:00:00.000Z&apikey=<your-api-key>
Request Description OData 2.2 Request
Returns total count of Inputs records (not supported in Microsoft Excel or Power BI). https://odata-trial.cognigy.ai/v2.2/Inputs/$count?apikey=<your-api-key>
Returns all Inputs records for the given API Key. https://odata-trial.cognigy.ai/v2.2/Inputs?apikey=<your-api-key>
Returns the first 10 Inputs records. https://odata-trial.cognigy.ai/v2.2/Inputs/?$top=10&apikey=<your-api-key>
Returns the top 5 Inputs records where executionTime is less than 50ms, ordered by executionTime. https://odata-trial.cognigy.ai/v2.2/Inputs/?$filter=executionTime lt 50&$top=5&$orderby=executionTime&apikey=<your-api-key>
Returns all Inputs records for a specific Cognigy.AI Project filtered by projectId. https://odata-trial.cognigy.ai/v2.2/Inputs/?$filter=projectId eq '<project-id>'&apikey=<your-api-key>
Returns all Inputs records and Session IDs for a specific Cognigy.AI Project. The request filters the data based on the projectId field and selects only the projectId and sessionId for each matching entry. https://odata-trial.cognigy.ai/v2.2/Inputs/?$filter=projectId eq '<project-id>'&$select=projectId,sessionId&apikey=<your-api-key>
Returns all Inputs records between two dates, for example, 1st Jan 2021 and 1st July 2021. https://odata-trial.cognigy.ai/v2.2/Inputs/?$filter=timestamp gt 2021-01-01T00:00:00.000Z and timestamp lt 2021-07-01T00:00:00.000Z&apikey=<your-api-key>

For a full reference, refer to the extensive collection of resources at OData.org and the Oasis OData URL Convention documentation.

Cognigy.AI OData Collections

The OData endpoint provides access to several data collections containing information about your interactions and workflows. The set of collections varies depending on which version you are using:

The current version of the OData endpoint is v2.3. In this version, the following OData collections are available:

The URL for accessing the v2.3 OData endpoint is as follows: https://<odata-domain>/v2.3/<collection>?apikey=<your-api-key>

Removal of OData v2.0–2.2

OData endpoint versions 2.0-2.2 were removed in Cognigy.AI v4.48.0.

  • Inputs (/Inputs) — renamed to Analytics in v2.3 Endpoint.
  • ChatHistory (/ChatHistory) — renamed to Conversations in v2.3 Endpoint.
  • Steps (/Steps)
  • ExecutedSteps (/ExecutedSteps)
  • Conversations (/Conversations) — renamed to Sessions in v2.3 Endpoint.

The URL for accessing the v2.X OData endpoint is as follows: https://<odata-domain>/v2.X/<collection>?apikey=<your-api-key>

Each collection can be filtered by its fields, which are often retrieved directly from the Input object results.

Analytics

The Analytics collection offers a log of comprehensive details such as organizational information, project identifiers, Flow specifics, and essential performance metrics. When a chat or voice AI Agent session happens in Cognigy.AI, it creates an Analytics record for the interaction. Each interaction is logged as a single record. The information is saved only after the entire session is finished. You can change this data by using the Overwrite Analytics Node.

Requests

Select one of the requests to extract data from the collection. Note that the API version in the request must match your version of Cognigy.AI.

https://odata-trial.cognigy.ai/v2.3/Analytics?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.2/Inputs?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.0/Inputs?apikey=<your-api-key>

Fields

When retrieving this collection, the endpoint will return the following fields:

Field Name Description Type Example
_id The unique ID of the record. String 5a91d194fde28b0011ce2423
organisation The name of your organization. String cognigy
projectId The ID of the Project related to the record. String 5a91d194fde28b0011ce2422
flowReferenceId The ID of the Flow. String 66ceb9cc-ac5b-4cdd-9f4b-8a48dfbb35d9
entrypoint The ID of the Project or Snapshot used by the Endpoint. String 621d3deb87016d3855ec0c92
ip The IP address from which the request originated. String 78.143.45.111
contactId The ID of the connecting user. String myContactID
sessionId The Session ID. String 5a91d194fde28b0011ce2425
inputId The ID of the input message. String 5a91d194fde28b0011ce2424
inputText The input text. String Hello World!
inputData The input data object as a string. String {"key":"value"}
state The state of the Flow at input. String default
mode A Mode of the input. String TextOnly
userType The type of the connecting user. Either external for external user or admin for admin user. String external
channel The channel through which the record was received. String facebook
flowLanguage The language of the Flow. String en-EN
intent The found Intent. This field can be empty. String orderFood
intentFlow The Parent ID of the Flow in which the Intent was found. This field can be empty. String 5e33b160e6236da3aa54221461a53f04
intentScore The numerical score of the input against a recognized Intent. This field can be empty. Number 0.836322430892043
completedGoalsList A 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, Intents or the message type was found. Boolean true
timestamp The date and time of the input. DateTime 2018-2-25T12:32:32.000Z
executionTime The time it took to execute the Flow in milliseconds. Number 32
execution The execution count. Number 3
custom1 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom2 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom3 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom4 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom5 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom6 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom7 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom8 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom9 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
custom10 The custom value created by Flow. The custom field has a maximum character limit of 1024. String custom value
localeReferenceId The reference ID for the locale. String 4bfdcf40-a605-4686-8e92-b17fa9f178af
localeName The name of the locale. String English
endpointUrlToken The URL token for the Endpoint. String ea30b8f20db52f9d86ea36fd55a7d66bd2c4c60eb24ac7ad52f1c9e173dd4cdb
endpointName The name of the Endpoint. String MyEndpoint
rating The rating for the session: -1 for a negative rating or 1 for a positive rating. Number 1
ratingComment The comment left when given a rating. String Great service!
snapshotName The name for the Snapshot used by the Endpoint. String Bot Release 2.2

Why is the Analytics Step label not used?

The analytics step label can be updated from the Cognigy.AI UI at any time. Therefore, to ensure compatibility between past and future data records, the entityReferenceId field is used. This field corresponds to either the Node ID or Intent ID assigned as an analytics step. The current analytics label of the step can be retrieved by mapping the entityReferenceID field to the Steps record.

Conversations

The Conversations collection offers a log of all session messages, including the end user, AI Agent, or human agent responses. Each time one of these sources sends a message to a Cognigy.AI Flow, Cognigy.AI creates a record to log the interaction. Each interaction is logged as a single record.

Requests

Select one of the requests to extract data from the collection. Note that the API version in the request must match your version of Cognigy.AI.

https://odata-trial.cognigy.ai/v2.3/Conversations?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.2/ChatHistory?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.0/ChatHistory?apikey=<your-api-key>

Fields

When retrieving this collection, the endpoint will return the following fields:

Field Name Description Type Example
_id The unique ID of the record. String 5a91d194fde28b0011ce2423
projectId The ID of the Project related to the record. String 5a91d194fde28b0011ce2422
projectName The name of the Cognigy.AI Project. String Project 1
inputId The ID of the input message. String 5a91d194fde28b0011ce2424
sessionId The Session ID. String 5a91d194fde28b0011ce2425
contactId The ID of the connecting user. String myContactID
organisation The Name of your organization. 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 The date and time of the input. DateTime 2018-2-25T12:32:32.000Z
flowName The name of the Flow. String MainFlow
flowParentId The Parent ID of the Flow. String 5e33b160e6236da3aa54221461a53f04
channel The channel through which the record was received. String facebook
inHandoverRequest A flag indicating whether the session is in a handover request. Boolean false
inHandoverConversation A flag indicating whether the session is in a handover session. Boolean true
outputId The output ID. String f514b7b2-7dc0-4e75-be62-a53fed5b2bb7

Steps

The Steps collection provides a list of all entities, which are either Nodes or Intents, assigned as analytics steps within any Flow. These steps are created in Cognigy.AI by setting a value in the Analytics Step field. For a step to appear in this OData collection, it must have been triggered at least once by a session within the Flow. Each step is logged as a single record.

Requests

Select one of the requests to extract data from the collection. Note that the API version in the request must match your version of Cognigy.AI.

https://odata-trial.cognigy.ai/v2.3/Steps?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.2/Steps?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.0/Steps?apikey=<your-api-key>

Fields

When retrieving this collection, the endpoint will return the following fields:

Field Name Description Type Example
_id The unique ID of the record. String 5a91d194fde28b0011ce2423
label The analytics step label defined for the entity (Node or Intent) in Cognigy.AI. String Question (2)
type The type of entity. String node or intent
entityReferenceId The unique ID for the entity (Node ID or Flow ID). String 5a91d194fde28b0011ce2423
flowReferenceId The ID of the Flow. String 5a91d194fde28b0011ce2423
flowName The name of the Flow where the step exists. String Main Flow
projectName The name of the Cognigy.AI Project. String Project 1
snapshotId The ID of the Snapshot. String 5e33b160e6236da3aa54221461a53f04
snapshotName The name of the Snapshot. String Bot Release 2.2

Building Visualizations with Steps Records

The Step Monitoring with OData article explains how these records can be manipulated in BI software to build insightful session path analytics.

ExecutedSteps

The ExecutedSteps collection logs all step events in sessions, including a reference to the prior (parent) step. Whenever a Node or Intent with an assigned step is executed, the collection creates a record for that step. Each step is logged as a single record.

Requests

Select one of the requests to extract data from the collection. Note that the API version in the request must match your version of Cognigy.AI.

https://odata-trial.cognigy.ai/v2.3/ExecutedSteps?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.2/ExecutedSteps?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.0/ExecutedSteps?apikey=<your-api-key>

Fields

When retrieving this collection, the endpoint will return the following fields:

Field Name Description Type Example
_id The unique ID of the record. String 5a91d194fde28b0011ce2423
userId The ID of the connecting user. String myContactID
sessionId The Session ID. String 5a91d194fde28b0011ce2425
inputId The ID of the input message. String 5a91d194fde28b0011ce2425
stepLabel The analytics step label defined for the entity (Node or Intent) in Cognigy.AI String Question (2)
parentStep The ID of the step that occurred prior to this step. String 5a91d194fde28b0011ce2425
type The type of entity. String node or intent
entityReferenceId The unique ID for the entity (Node ID or Intent ID). String 5a91d194fde28b0011ce2423
flowReferenceId The ID of the Flow. String 5a91d194fde28b0011ce2423
flowName The name of the Flow where the step exists. String Main Flow
timestamp The date and time when the step was executed. DateTime 2018-2-25T12:32:32.000Z
projectName The name of the Cognigy.AI Project. String Project 1
projectId The ID of the Project related to the record. String 6067352c18887e471da4e392
organisationId The ID of the Cognigy.AI organization associated with the record. String 5f8833dae72b850ad2ed4d53
snapshotId The ID of the Snapshot. String 5e33b160e6236da3aa54221461a53f04
snapshotName The name of the Snapshot. String Bot Release 2.2

Sessions

Version badge

The Sessions collection contains a list of all sessions that have occurred. The primary objective of this collection is to provide a list of the analytics steps that took place in any given session, along with the order of execution. This information is included as a comma-separated list within a field called stepPath. Each session is logged as a single record.

Requests

Select one of the requests to extract data from the collection. Note that the API version in the request must match your version of Cognigy.AI.

https://odata-trial.cognigy.ai/v2.3/Sessions?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.2/Conversations?apikey=<your-api-key>

https://odata-trial.cognigy.ai/v2.0/Conversations?apikey=<your-api-key>

Fields

When retrieving this collection, the endpoint will return the following fields:

Field Name Description Type Example
_id The unique ID of the record. String 5a91d194fde28b0011ce2423
goals All the goals that were achieved in the session. String Goal1, Goal2
stepPath A comma-separated list of executed steps. String 9ac4f679-beae-4461-b9e3-43aece8b3430,f1e72fe3-f04b-48f5-b862-1e35ad253f18, ...
stepsCount The count of the number of steps. Number 10
handoverEscalations The number of times the session triggered a handover. Number 3
startedAt The date and time when first message was received. DateTime 2018-2-25T12:32:32.000Z
userId The ID of the connecting user. String myContactID
sessionId The Session ID. String 5a91d194fde28b0011ce2425
localeReferenceId The ID of the locale. String 7eff993c-b801-4556-b111-1c319e8577cf
localeName The name of the locale. String English
endpointReferenceId The ID of the Cognigy.AI Endpoint. String 5e33b160e6236da3aa54221461a53f04
endpointName The name of the Cognigy.AI Endpoint. String Webchat
projectName The name of the Cognigy.AI Project. String Project 1
projectId The ID of the Project related to the record. String 6067352c18887e471da4e392
organisationId The ID of the Cognigy.AI organization associated with the record. String 5f8833dae72b850ad2ed4d53
snapshotId The ID of the Snapshot. String 5e33b160e6236da3aa54221461a53f04
snapshotName The name of the Snapshot. String Bot Release 2.2

LiveAgentEscalations

Version badge

Description

The LiveAgentEscalations collection contains records from Cognigy Live Agent and includes the related data about handovers to Live Agent. Each handover (escalation) is logged as a single record.

Request

https://odata-trial.cognigy.ai/v2.3/LiveAgentEscalations?apikey=<your-api-key>

Fields

When retrieving this collection, the endpoint will return the following fields:

Field Name Description Type Example
_id The unique ID of the record. String 649be849b7fd71d48b9bacc8
organisationId The ID of the Cognigy.AI organization associated with the record. String 5eb4a49d426cd3d05f2892a9
projectId The ID of the Project related to the record. String 6409b6c53c9687b5e78e6403
sessionId The Session ID. String session-2a38246e-0395-49a5-876d-dd5133fd5418
timestamp The date and time when the record was created. DateTime 2023-06-28T07:59:04.628Z
localeName The Name of the locale. String en
status The current status of the escalated conversation in Live Agent. The possible statures are: opened, assigned, resolved, and abandoned. String opened
inboxId The ID of the inbox associated with the record. String 7983
inboxName The name of the inbox. String LA Chatbot-default
teamId The ID of the team assigned to the conversation. String 8
teamName The name of the team assigned to the conversation. String IT Support
labels The list of labels assigned to the conversation. Array [Hardware]
agentId The ID of the human agent assigned to the conversation. String 618cf7687614774ba028dcac
agentName The name of the human agent assigned to the conversation. This field is supported from Cognigy.AI 4.80. String John Doe
contactId The ID of the connecting user. String 649ba8450d5df5cadf8b75b8
endpointName The name of the Cognigy.AI Endpoint. String LA Chatbot
endpointType The type of the Endpoint. String webchat2
endpointUrlToken The URL token for the Endpoint. String ea30b8f20db52f9d86ea36fd55a7d66bd2c4c60eb24ac7ad52f1c9e173dd4cdb
channel The channel through which the record was received. String admin-webchat
localeReferenceId The ID of the locale. String 7eff993c-b801-4556-b111-1c319e8577cf
snapshotId The ID of the Snapshot. String 63ff0cc47a466cab278fd19b
endpsnapshotName The name of the Snapshot. String Prod-Snapshot 26.7.23

Cognigy.AI OData Collections: Entity Relationship Diagram (ERD)

The Entity Relationship Diagram (ERD) describes the relationships between the collection entities.

Entity Relationship Diagram

Integrations

The Cognigy.AI OData endpoint can integrate with all tools compatible with OData protocol version 4. The table outlines popular integration tools, including data visualization tools, recommended for integration.

Tool Description
Microsoft Excel Microsoft Excel is a spreadsheet application widely used for data analysis and reporting. When connecting from Microsoft Excel 2016, use the PowerQuery feature, which can be found under Data > Get & Transform > New Query > From Other Sources > From OData Feed.
Microsoft Power BI Microsoft Power BI is a business analytics service that provides interactive visualizations and business intelligence capabilities. For for integrating with the Cognigy.AI OData endpoint, refer to the Microsoft Power BI documentation.
OData Consumer Ecosystem The OData Consumer Ecosystem encompasses a variety of tools and applications that support the consumption of OData services. For a full list of available OData Consumer options, refer to the OData documentation.
Client Libraries in .NET, Java, JavaScript, C++ and other platforms Client libraries are available in multiple programming languages and platforms, providing developers with OData protocol implementations. For a full list of available libraries, refer to the OData documentation.

If you want to use another tool not listed in the table, verify its compatibility with the OData endpoint on the OData website and in the tool's documentation before integrating. For example, the data visualization tool Tableau cannot be used for integration because it does not support OData protocol version 4 on which the OData endpoint is based.

More Information


  1. Microsoft Excel and Power BI do not support for the $count query. Use Postman or other options. To perform this query, consider using tools such as Postman or other applications that support advanced API querying.