Overview

Genesys Cloud provides a rich set of APIs to perform ad-hoc queries, batch processing support, and data exports of your agent performance and customer/agent interactions. However, with the level of sophistication these query APIs provide, it is often difficult to ascertain which Analytics API is appropriate for a given situation. There are two key items that need to be considered as you look at your individual use cases:

Data Perspective

A contact center is an extremely rich source of data for how your customers interact with your organization. However, those customer interactions can be viewed from multiple perspectives and each perspective is useful based on the the context in which the data is consumed. The Genesys Cloud Analytics API supports three different perspectives on the users of the platform and your customers. These three perspectives are:

Instantaneous Observations metrics. A snapshot of metrics of what is going on in your contact center at that moment in which the API is called.
Aggregate metrics. KPIs and metrics that occur over a period of time and are broken down into buckets of time.
Detail Record metrics. Audit style records that capture a very fine-grained level of detail around user (e.g. agent) and customer interactions.

Instantaneous Observations metrics

The metrics returned by the Instantaneous Observations API are a snapshot of what is going on right now within your contact center. This API provides the most current data about your contact center, but often lacks important context to perform historical trending and detailed data analysis. For example, the Instantaneous Observations API does not provide any kind of timestamp on the data being returned or aggregation capabilities.

Genesys Cloud supports Instantaneous Observations metrics on three subject areas: flow, queue and user status. These subject areas are listed below along with links to additional documentation:

Observation Type	Description	Example Use Case(s)
Flow	Returns a single metric showing currently observed flow interactions.	Note: There is no additional documentation for the flow observations. The link will take you to the endpoints page for analytics.
Queue	The queue observations query shows instantaneous data about one or more queues in your organization.	This API's metrics are focused on such things as: how many interactions are ongoing/waiting right now as well as which agents are available. This API is not appropriate if you need "slice-and-dice" data capabilities or the individual components involved in a conversation (e.g. talk time).
User Status	The user observations query shows instantaneous data about one or more Genesys Cloud users	This API can be used to answer questions like: how many queues a particular user( e.g. agent) is active on and of what queues they are a member.

Aggregate metrics

The Aggregate Metrics API offer metrics over a time interval. The Aggregate Metrics API offers a richer querying model than the Instantaneous Observations API. The Aggregate Metrics supports SQL-like filtering and a grouping mechanism. In addition, the data retrieved by the Aggregate Metrics API can be grouped into time buckets ranging from minutes to days. The Aggregate Metrics API includes the following subject areas:

Aggregate Type	Description	Example Use Case(s)
Conversations	Retrieve aggregate metrics for customer/agent interactions. The retrieved metrics are placed in buckets of time.	Give me the agent talk time on the "customer support" queue for all interactions that took place last month. Aggregate the data into one-day-sized buckets grouped-by user ID and wrap-up code.
Evaluations	Retrieve customer provided service evaluations about customer/agent interactions.	Give me the average critical scores on the "customer support" queue for all interactions last month aggregated into one-day-sized buckets grouped-by user ID and form ID.
Flow	Retrieve aggregate metrics for how users interacted with a flow.	Give me the average amount of time spent in an IVR flow that a user ultimately abandoned.
User Status	Retrieve high-level summary of user activity. The query data reflects the user's Genesys Cloud presence as well as their ACD routing status.	Give me agent presence and ACD routing status for a problem agent of mine over the last week aggregated into one-hour--sized buckets so I can see how much of the day that agent spent on break/at a meal/etc in relation to how long that agent spent on queue servicing interactions.

Detail Record metrics

The Details Record API consist of audit level records that track events and interactions down to the specific time in which they happened. They offer the richest amount of detail around the occurrence of a specific event. There are currently only two types of detail records available within Genesys Cloud: user and conversations.

Detail Type	Description
User	Returns the finest level of user activity. The query data reflects the user's Genesys Cloud presence as well as their ACD routing status at the individual status-change level
Conversation	Returns complete details of who was present, in what state, and when during the full life of a conversation

Synchronous vs Asynchronous data access

While Genesys Cloud provides a different perspectives on your contact center data, one of the most common requests we hear from customers is that they want to be able to retrieve detailed user and conversation data and then perform their own analysis in a manner that they see fit. The individual use cases for this detailed data retrieval can be highly variable and can range from building near-time dashboards customized to their own unique data needs to synchronizing detailed user and customer data with their own data warehouses.

Unfortunately, this is where new Genesys Cloud developers can get themselves into trouble. The user and conversation detail API are designed for ad-hoc queries and not designed to be constantly polled and are limited in scope for the length of time in which data can be retrieved.

For extracting and and synchronizing large amounts of detail data from Genesys Cloud, the Analytics API team has four mechanisms for doing this: user detail jobs, conversation detail jobs, analytics notifications, and exports.

Type	Description
User Details Job	Provides an asynchronous API-based mechanism to retrieve user detail information.
Conversation Details Job	Provides an asynchronous API-based mechanism to retrieve conversation detail information
Analytics Notifications	Provides an asynchronous, web-sockets, messaging-based protocol for synchronizing user and conversation detail.
Export	Programmatic way to kick off an export of analytics data. However, the exported data is only retrievable from the Genesys Cloud UI.

The style of data integration you use can vary heavily based on your use case. Please take a look at the Data Integration Guide for more guidance on selecting which Analytics API is appropriate for your needs.

NOTE: If any of the notification topics provides the data you are interested in, you should always subscribe to notifications instead of polling the corresponding endpoints. For aggregates and observations, you may want to perform one initial query and then use notifications to update values.

Additional Resources

Analytics Query API overview DevCast - Learn the best practices, tips, and tricks for retrieving data from Analytics using the APIs
Additional documentation on Query syntax:
Query Metrics
Query Dimensions
Aggregate query syntax
Detail record query syntax
Analytics Query Builder in API Explorer - A powerful web-based tool that lets build analytics queries without having to write code. It will also generate the JSON structure for a query for use within your own code.