Skip to main content
Live Agent exposes an OData 4 analytics endpoint to retrieve analytics records. OData, the best way to REST, is a powerful API framework. The OData endpoints allows you to retrieve the most relevant data models from Live Agent by using GET requests. It covers all your enterprise analytics needs to make fine-grained queries in your spreadsheets or build rich dashboards for your bots with your favorite data visualization tool. The Live Agent OData endpoint supports only GET requests and doesn’t support any other request types, such as PATCH, DELETE, or POST.

​
Usage and Authentication

To connect to the OData endpoint, get a Live Agent Access Token:
  1. In the left-side menu of the Live Agent interface, go to Profile Settings.
  2. In the Access Token section, copy the existing token.
  3. Paste this token into your OData request.
An OData URL is composed of the service root, API version, service path, data collection, and Live Agent access token parameter as follows: 
GET /<api-version>/odata/<OData data model>?<odata query> HTTP/1.1
Host: <odata domain>
Authorization: Bearer <Live Agent access token>
The authentication can also be done using a query param such as follows: 
/<api-version>/odata/<OData data model>?<odata query>&$top=1&$skip=0&apikey=<Live Agent access token>
The OData endpoint is available on a different domain from your Cognigy User Interface domain. For example, https://odata-liveagent-trial.cognigy.ai/v1.0/odata.For example, on our trial server, the OData endpoint URL for the Analytics Inputs Collection is https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Message?. For on-premises installations, replace the odata-trial.cognigy.ai domain name with the domain name configured for your local installation.
When using PowerBI or Excel, you might be asked to authenticate. Simply choose anonymous authentication and pass the Live Agent access token as a query parameter &apikey=<Live Agent access-token>

​
Endpoint Versions

  • Version 1.1
  • Version 1.0
This endpoint version is available for Live Agent 2025.18.0 onwards. In this version, the following OData collections are available:To see all the available OData models, you can use the following Endpoint: https://<hostname>/v1.1/odata/The URL for accessing the OData endpoint 1.1 is the following: https://<hostname>/v1.1/odata/<collection>

​
Querying

The Endpoint supports the following OData Query Language operators:
  • $skip1
  • $top1
  • $filter
  • $select
  • $orderby
  • $expand

​
Example Queries

  • Version 1.1
  • Version 1.0
https://odata-liveagent-trial.cognigy.ai/v1.1/odata/Conversation(1)?$select=inbox_id,account_id&$top=1&$skip=0&apikey=<access-token> Return the columns inbox_id and account_id for the Conversation with id=1.https://odata-liveagent-trial.cognigy.ai/v1.1/odata/Conversation?$select=id,account_id&$top=1&$skip=0&apikey=<access-token> Return the columns’ ID and account_id for all Conversations.https://odata-liveagent-trial.cognigy.ai/v1.1/odata/Conversation?$select=id,account_id&$top=1&$skip=0&$filter=created_at le '2021-11-23T00:00:00'&$top=1&$skip=0&apikey=<access-token> Return the columns’ ID and account_id for all the Conversations filtered by the created_at column being lower or equal to ‘2021-11-23T00:00:00’

​
Reference Documentation

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

​
Data Protection & Analytics

Only users with an admin role in Live Agent will be able to query OData Models.

​
Live Agent OData Collections

This section details the data types that exist within the OData Collections that can be retrieved from the OData endpoint. The following Collections are available:

​
Message

Description:
  • Version 1.1
  • Version 1.0
https://odata-liveagent-trial.cognigy.ai/v1.1/odata/Message?$top=1&$skip=0
Data Types: When retrieving this data model, the endpoint returns the following fields:
  • Version 1.1
  • Version 1.0
Field NameDescriptionTypeExample
idUnique message IDNumber1
contentThe message sentStringWelcome to Live Agent
account_idAccount IDNumber1
inbox_idInbox IDNumber1
conversation_idConversation IDNumber1
message_typeType of message { incoming: 0, outgoing: 1, activity: 2, template: 3 }Number3
created_atMessage Creation DateDate2023-01-19T13:31:18.553Z
updated_atMessage Updated DateDate2023-01-19T13:31:18.553Z
privateMessage VisibilityBooleanfalse
statusMessage Status { sent: 0, delivered: 1, read: 2, failed: 3 }Number3
source_idMessage source IDStringdefault
content_typetext: 0, input_text: 1, input_textarea: 2, input_email: 3, input_select: 4, cards: 5, form: 6, article: 7, incoming_email: 8, input_csat: 9, typescognigy: 2016, request_file_upload: 2017Number0
content_attributesJSON Attribute/Value DefinitionsJSON{"items":[{"title":"Acme Hardware"}]}
sender_typeProvides information on who originated the messageStringcognigy
sender_idSender unique IDNumber1

​
Conversation

Description: A Conversation is the communication channel opened between an Agent and a client. Example Query:
  • Version 1.1
  • Version 1.0
https://odata-liveagent-trial.cognigy.ai/v1.1/odata/Conversation?$top=1&$skip=0
Data Types: When retrieving this data model, the endpoint returns the following fields:
  • Version 1.1
  • Version 1.0
Field NameDescriptionTypeExample
idUnique conversation IDNumber1
account_idAccount ID (where the conversation belongs)Number1
inbox_idInbox ID (where the conversation belongs)Number1
statusConversation status: { open: 0, resolved: 1, pending: 2, snoozed: 3 }Number1
assignee_idAgent ID (assigned to the conversation)Number1
created_atConversation creation dateDate2023-01-19T13:31:18.553Z
updated_atConversation updated dateDate2023-01-19T13:31:18.553Z
contact_idClient unique identificationNumber3
display_idDisplay IDNumber3
contact_last_seen_atContact/Client date last seenDate2023-01-19T13:31:18.553Z
agent_last_seen_atAgent date last seenDate2023-01-19T13:31:18.553Z
additional_attributesJSON containing any additional attributesJSON{}
contact_inbox_idContact Inbox IDNumber1
uuidUnique identifierString89f20666-e17d-427c-9283-268ba7870283
identifierIdentifierString89f20666-e17d-427c-9283-268ba7870283
last_activity_atLast activity dateDate2023-01-19T13:31:18.553Z
team_idTeam ID (belonging to the conversation)Number1
snoozed_untilSnoozed date endDate2023-01-19T13:31:18.553Z
custom_attributesExtra add-on attributesJSON{}
assignee_last_seen_atDate of last time the assignee has been seenDate2023-01-19T13:31:18.553Z
cognigy_session_idUnique session IDString”session-deedb62a-8062-490f-83ac-826de9ef94S3”

​
Inbox

Description: The Inbox is where all Conversations from a specific set of Agents will be placed. Example Query:
  • Version 1.1
  • Version 1.0
https://odata-liveagent-trial.cognigy.ai/v1.1/odata/Inbox?$top=1&$skip=0
Data Types: When retrieving this data model, the endpoint returns the following fields:
  • Version 1.1
  • Version 1.0
Field NameDescriptionTypeExample
idUnique record IDNumber1
channel_idChannel IDNumber1
nameInbox nameStringWelcome to Live Agent
email_addressEmail addressStringai-agent@cognigy.com
account_idAccount IDNumber1
created_atInbox creation dateDate2023-01-19T13:31:18.553Z
updated_atInbox updated dateDate2023-01-19T13:31:18.553Z
channel_typeCommunication channel, for example, API, Webchat, Facebook (Meta)StringChannel:Webchat
enable_auto_assignmentFeature that allows the agent to auto assign conversationsBooleantrue
greeting_enabledFeature that allows an automatic greeting to be sentBooleanfalse
greeting_messageAutomatic greeting messageStringHi there!
working_hours_enabledFeature that enables a working hours timetableBooleantrue
out_of_office_messageFeature that enables a working hours timetableBooleantrue
timezoneInbox timezoneString”UTC”
enable_email_collectAllows email collectionBooleantrue
csat_survey_enabledAllows CSAT surveyBooleantrue
cognigy_organization_idCognigy account IDString1
cognigy_project_idCognigy Project IDString1
enable_auto_reassignmentAllows conversation reassignmentBooleantrue
conversation_show_allAllows to see all conversations in Inbox, even if they don’t belong to youBooleantrue

​
Label

Description: Labels are used to mark, identify or group different Conversations. Example Query:
  • Version 1.1
  • Version 1.0
https://odata-liveagent-trial.cognigy.ai/v1.1/odata/Label?$top=1&$skip=0
Data Types: When retrieving this data model, the endpoint returns the following fields:
  • Version 1.1
  • Version 1.0
Field NameDescriptionTypeExample
idUnique label IDNumber1
titleLabel titleStringlabel-complain
descriptionLabel descriptionStringlabels used for complains
colorLabel colorStringred
show_on_sidebarAllows the label to be shown on the sidebarBooleantrue
account_idAccount to which the label will belongNumber3
created_atLabel creation dateDate2023-01-19T13:31:18.553Z
updated_atLabel updated dateDate2023-01-19T13:31:18.553Z

​
Reporting Event

Description: The Reporting Event model represents actions or occurrences tracked in the system for reporting and analytics purposes. Example Query:
  • Version 1.1
  • Version 1.0
https://odata-liveagent-trial.cognigy.ai/v1.1/odata/ReportingEvent?$top=10&$skip=0.
Data Types: When retrieving this data model, the endpoint returns the following fields:
Field NameDescriptionTypeExample
idUnique Reporting Event IDNumber4
event_start_timeStart time of the eventDate2023-01-08T18:34:43.162Z
event_end_timeEnd time of the eventDate2023-01-08T18:34:43.162Z
nameName of the eventStringmessage_created, conversation_resolved, first_reply_created, assignee_changed, conversation_inbox_changed
valueValue associated with the event, such as timestampNumber1
created_atThe date and time when the event was createdDate2023-01-08T18:34:43.213Z
updated_atThe date and time when the event was last updatedDate2023-01-08T18:34:43.213Z
account_idID of the account associated with the eventNumber2
conversation_idID of the conversation associated with the eventNumber1
inbox_idID of the inbox associated with the eventNumber1
user_idID of the user associated with the eventNumber3
To avoid potential query timeouts due to large data volumes, use the $top query option to limit the number of returned records.### User

​
User

Description: This data model holds information regarding the Live Agent users, such as an Agent. Example Query:
  • Version 1.1
  • Version 1.0
https://odata-liveagent-trial.cognigy.ai/v1.1/odata/User?$top=1&$skip=0
Data Types: When retrieving this data model, the endpoint returns the following fields:
  • Version 1.1
  • Version 1.0
Field NameDescriptionTypeExample
idUnique record IDNumber1
providerFor example, emailStringemail
uidProvided unique identifierStringsome-email@cognigy.com
encrypted_passwordEncrypted passwordString$2a$11$L.610bE0k617uÜiXy9L3H0q8nn6kdjJK2/X4p7ghlxPC38hjovasd
reset_password_tokenToken used to reset the passwordString$2a$11$L.610bE0k617uÜiXy9L3H0q8nn6kdjJK2/X4p7ghlxPC38hjsvaru
reset_password_send_atDate when a password reset was sentDate2021-12-11 12:41:26.745
remember_created_atDate of remember creationDate2021-12-11 12:41:26.745
sign_in_countNummber of times the user has signed inNumber3
current_sign_in_ipCurrent sign in IP addressString120.0.0.1
last_sign_in_ipLast sign in IP addressString120.0.0.1
confirmation_tokenConfirmation tokenString$2a$11$L.610bE0k617uÜiXy9L3H0q8nn6kdjJK2/X4p7ghlxPC38hjovasd
confirmed_atConfirmation token confirmed at dateDate2021-12-11 12:41:26.745
confirmation_sent_atConfirmation token sent at dateDate2021-12-11 12:41:26.745
unconfirmed_emailUnconfirmed emailStringunconfirmed@cognigy.com
nameUser nameStringFrancisco
display_nameUser display nameStringPaco
emailUser emailStringfran@cognigy.com
tokensUser tokensJSON{"MN4iNP38tvwe5wer7pvpnAQ":{"token":"$2a$10$iA7Si0sBV9lMkO2mqvwiD.L90.uTCl27WQbEo/Kc0W","expiry":1644763988}}
created_atUser creation dateDate2021-12-11 12:41:26.745
updated_atUser updated dateDate2021-12-11 12:41:26.745
pubsub_tokenUser publish/subscribe tokenStringMiVxY3FKry6oklambiuqL72nn
availabilityThis represents the user’s availabilityNumber1
ui_settingsUI settings for userJSON{"is_conv_actions_open": true, "is_contact_sidebar_open": true}
custom_attributesCustom attributesJSON{}
cognigy_user_idCognigy user IDstring610bEOk617uPiXy9L3HOq8nn6kdjJK2
sign_in_countThe total number of times the user has logged in to Live AgentNumber3
current_sign_in_atThe date and time of the user’s most recent loginDate2021-12-11 12:41:26.745
last_sign_in_atThe date and time of the user’s login previous to the current oneDate2021-12-11 12:41:26.745

​
Integrations

​
Excel

When connecting from Microsoft Excel 2016, you must use the Power Query feature, which can be found under Data > Get & Transform > New Query > From Other Sources > From OData Feed. This will connect to our OData 4 feed.

​
Power BI

Follow the instructions in the Power BI documentation.

​
Tableau

Cognigy.AI supports OData 4.0, which implies that certain versions of Tableau aren’t compatible.
Find instructions on how to connect an OData Feed in the Tableau documentation.

​
OData Consumer Ecosystem

For a full list of available OData Consumer options, 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, see the latest directory of available libraries on OData.org.
1: This parameter is required to make a request to the Live Agent OData endpoint.