Log Usage Analytics Events

This section provides guidelines for performing HTTP requests against the Usage Analytics Write API to properly log different types of events.

The Coveo JavaScript Search Framework components provide out-of-the-box logging for search, click, and custom usage analytics events. The coveoua script handles HTTP requests for logging view events (see Push Coveo Usage Analytics View Events). If, for some legitimate reason, you can’t use the Coveo JavaScript Search Framework or the coveoua script in your search integration with the Coveo Platform, but must rather use your own custom search interface implementation, you must still ensure that end-user interactions with your search interface log usage analytics events properly (i.e., in a similar fashion to what a search interface relying on the Coveo JavaScript Search Framework and the coveoua script does).

The convention is to use POST methods to send data to a server and GET methods to retrieve data from a server. Although it’s still possible to log UA events using the GET endpoints, these methods have now been deprecated and will stop working entirely in November 2021.

In the HIPAA environment, you can only use the POST endpoints to log UA events.

Generic Guidelines

The following guidelines apply when logging any type of event through the Usage Analytics Write API.

  • Follow all recommended standard practices when logging usage analytics events, respecting the syntax and the nomenclature.

    Using custom names will require significant customization down the road because standard names and values are used by:

    These services might therefore not work correctly when names are changed.

    Additionally, if you use both a search interface powered by the Coveo JavaScript Search Framework and a custom search interface with custom names in your organization, your usage analytics data will be heterogeneous. You and your Coveo Customer Success manager will struggle to make sense out of it.

  • Log usage analytics events asynchronously.

    Don’t make end users wait for Usage Analytics Write API responses.

  • Contact Coveo Professional services to ensure that the information passed to Coveo Usage Analytics (Coveo UA) fits your needs.

    The passed data should reflect the information you want to track over usage analytics and how you want to track it. The information you want to track is typically related to usage monitoring or improvement seeking (e.g., identify content gaps, improve case deflections). Some tests could be required to ensure that the proper data is passed down.

    • You have many agents using an application.

      Perhaps you would like to pass information about the role, department, and level of agent to categorize or group them. As much as possible, such groupings should be made when logging events (using customData) rather than when reporting (using filters). There are two main reasons for this:

      1. When logging search and click events, grouping agents allows the Coveo Machine Learning (Coveo ML) service to learn from said groups (see Search Event customData and Click Event customData).

      2. At report time, having existing groups is a lot more efficient. Adding large numbers of filters to group agents is inefficient, both when designing dashboards and when the Usage Analytics Read service feeds those dashboards.

      When logging usage analytics events, you would therefore include, in the customData property of your request body, key-value pairs such as:

      • "context_role":"<context_role>"

      • "context_department":"<context_department">

      • "<context_level>":"<context_level">


      • <context_role> is the role of the agent sending the request.

      • <context_department> is the department of the agent sending the request.

      • <context_level> is the level of the agent sending the request.

    • You’re doing application support, where the target is to maximize the case deflection and minimize the case creation.

      In such case, it’s important to track the case creation event, case cancellation, and other events related to the case itself, since it will help in determining the number of created and deflected cases (implicitly or explicitly when there’s a cancel case event). The same applies for commerce, where adding item to carts, dropping carts, etc. could be important events to track.


The Usage Analytics Write API relies on the bearer HTTP authentication scheme. All HTTP requests made to log usage analytics events must include an Authorization header with a valid access token such as an API key or a search token (see Choosing and Implementing a Search Authentication Method):

Authorization: Bearer <token>

The <token> must grant the Analytics - Analytics data - Push privilege in the target Coveo organization.

If a Usage Analytics Write API request is authenticated using an OAuth2 token, the search interface needs to specify a value for the org query parameter, as OAuth2 tokens are platform-wide and can therefore allow access to more than one Coveo organization. Otherwise, the org value is extracted from the search token.

org (string); the name of the organization.

For example: myorg - myorg6j53h4

Tracking Sessions and Visitors

For both usage analytics reporting and Coveo ML, it’s useful to track individual visitors and their activities.


The visitor (string) query parameter is the never expiring unique identifier of the visitor. It has a maximum length of 128 ASCII characters, and the best practice is to use a v4 UUID. If the visitor value exceeds 128 ASCII characters in length, the service truncates it, which can result in conflicts. If no visitor value is provided, a new identifier is created and returned both as an HTTP visitor cookie and as the visitorId property in the query response.

Record this newly generated identifier and use it in future requests. It should be included in the cookie, but also as the visitor parameter, in case the user browser doesn’t support third party cookies.

Unless the prioritizeVisitorParameter (Boolean) query parameter is explicitly set to true, the visitor query parameter is overridden by the visitor cookie whenever it’s present.

Sometimes, you may want to force the Usage Analytics Write service to use the visitor query parameter rather than the visitor cookie. If that’s the case, set the prioritizeVisitorParameter query parameter to true.

You have several applications integrated with Coveo Cloud, and you want to track end users across those applications in order to benefit from meaningful reporting and ML.

Instead of letting the Usage Analytics Write service handle the visitor values for you, which would generate as many visitor values per end user as you have applications, you generate one visitor per end-user, and you force the service to use it by passing it as visitor query parameter value, and by setting prioritizeVisitorParameter to true.

The Coveo ML Automatic Relevance Tuning (ART), Query Suggestions (QS), and Event Recommendations (ER) models use the visitor value to personalize learning to the user.



The visitId tracks individual visits of users and expires after 30 minutes of inactivity. visitId is entirely handled server-side by Coveo UA, you can’t generate it.

The Coveo ML ART, QS, and ER models use the visitId value to track sequences of events and learn from them.

  • A visitId value is a GUID similar to the following:


  • A request URL and header to log a custom event, where an API key with Analytics - Analytics data - Push privileges is provided in the header, and the visitor query parameter is passed in the URL. The org parameter need not be included since the organization will be retrieved from the API key.

POST https://analytics.cloud.coveo.com/rest/ua/v15/custom?visitor=28s6g49d-f81s-1435-2r5x153dle72
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
Cookie: visitor=28s6g49d-f81s-1435-2r5x153dle72

In such a case, the visitor Cookie is automatically added by the browser.

What’s Next?

Recommended Articles