Log Usage Analytics Events

This section provides guidelines for performing HTTP requests against the Usage Analytics (UA) 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 and generic Collect events. If, for some legitimate reason, you can’t use the 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 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 December 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 UA Write API.

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

    The following services may not work correctly if you don’t use the standard names and values:

    Additionally, if you use both a search interface powered by the 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 of it.

  • Log events asynchronously.

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

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

    The data that you pass should reflect the information that you want to track over usage analytics and how you want to track it. This information is typically related to monitoring usage or seeking improvements (e.g., identifying content gaps or improving case deflections). Some tests could be required to ensure that the proper data is passed to Coveo UA.


  1. 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 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 UA 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.

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

    In this situation, 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 items to carts, dropping carts, etc. could be important events to track.


The UA 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.

Tracking Sessions and Visitors

It’s useful to track individual visitors and their activities for both usage analytics reporting and Coveo ML.


The visitor (string) query parameter is the never expiring unique identifier of the visitor. It has a maximum length of 128 ASCII characters,[1] and the best practice is to use a v4 UUID, as in the following example:


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 UA 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 UA 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 is a GUID similar to the following:


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

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


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 doesn’t need to 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 HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
Cookie: visitor=28s6g49d-f81s-1435-2r5x153dle72

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

1. If the visitor parameter exceeds 128 ASCII characters in length, the service truncates it, which can result in conflicts.
Recommended Articles