---
title: Log click events
slug: '2064'
canonical_url: https://docs.coveo.com/en/2064/
collection: build-a-search-ui
source_format: adoc
---
# Log click events

A [search interface](https://docs.coveo.com/en/2741/) typically logs a click event whenever a user clicks or previews a [query](https://docs.coveo.com/en/231/) result.
Click events are required to feed several [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) and to enable [Coveo Analytics reporting](https://docs.coveo.com/en/266/).

This article provides guidelines for performing HTTP requests against the [Usage Analytics (UA) Write API](https://docs.coveo.com/en/18/) to properly log click events.

> **Important**
>
> The information in this article is only relevant when you can't (or choose not to) use one of the Coveo UI libraries ([Atomic](https://docs.coveo.com/en/lcdf0264/), [Headless](https://docs.coveo.com/en/lcdf0493/), or the [JavaScript Search Framework](https://docs.coveo.com/en/187/)) to achieve a search integration with Coveo.
> These libraries can handle all of the HTTP requests for you.

To log a click event, make a POST request to

[source,text,subs="attributes+"]
```
https://<ORG_ID>.analytics.org.coveo.com/rest/ua/v15/analytics/click
```

where `<ORG_ID>` is the unique identifier of your [Coveo organization](https://docs.coveo.com/en/185/).

In the HIPAA environment, use:

[source,text,subs="attributes+"]
```
https://<ORG_ID>.analytics.orghipaa.coveo.com/rest/ua/v15/analytics/click
```

> **Note**
>
> In either case, under the hood, Coveo will use the [organization endpoints](https://docs.coveo.com/en/mcc80216/) to redirect your requests to the target region.

Use an access token with the [privilege](https://docs.coveo.com/en/228/) to push [Coveo Analytics data](https://docs.coveo.com/en/259/) (that is, the **Allowed** [access level](https://docs.coveo.com/en/2818/) on the [**Analytics data**](https://docs.coveo.com/en/1707#analytics-data-domain) [domain](https://docs.coveo.com/en/2819/)).

## Example

In the following request, only the body properties which are required by the [Coveo Analytics](https://docs.coveo.com/en/182/) and [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) services are included.
In this example, even though the `username` is required, it's not included because it's extracted from the [search token](https://docs.coveo.com/en/1346/).
If another authentication method was used, the `username` field would need to be included in the request body.

[source,http,subs="attributes+"]
```
POST https://myorganizationid9sd8df7s.analytics.org.coveo.com/rest/ua/v15/analytics/click HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

Payload:

```json
{
  "anonymous": false,
  "clientId": "489aa3e3-aed2-4563-8e81-62bb73178a56",
  "actionCause": "documentOpen",
  "documentPosition": 2,
  "documentTitle": "Coveo for Salesforce",
  "documentUrl": "https://docs.coveo.com/en/1243/",
  "language": "en",
  "originLevel1": "ExternalSearch",
  "originLevel2": "All",
  "searchQueryUid": "df60b2fb-c276-49ae-b704-2ee45609f3a6",
  "sourceName": "AnswersCloud",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
  "customData": {
    "contentIDKey": "permanentid",
    "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960"
  }
}
```

## Required request body properties

The following properties are required by the UA Write API when logging a click event.

### `actionCause` (string)

The identifier of the user action that
caused the search interface to log a click event.
For example, if the user
opens a query result,
the standard `actionCause` value would be
`documentOpen`.

Most of the actions which can be performed from a typical search interface are associated with a specific, standard `actionCause` value (that is, the one that the Coveo UI libraries would use in a similar situation).

The most common of these are documented in the search interface [implementation guidelines](https://docs.coveo.com/en/1370/).

To learn more about the different `actionCause` values, see [Custom metadata reference](https://docs.coveo.com/en/1522/).

> **Note**
>
> Some `actionCause` values are expected to be accompanied by a specific set of [`customData`](https://docs.coveo.com/en/1502#search-event-customdata-key-value-pairs) key-value pairs.
> Passing these expected key-value pairs is important because they're used by Coveo ML and in [Coveo Analytics reports](https://docs.coveo.com/en/266/).

```json
{
  ...
  "actionCause": "documentOpen",
  ...
}
```

### `documentPosition` (unsigned integer)

The position of the [item](https://docs.coveo.com/en/210/) (one-based) that was clicked in the list of results.
If unavailable, set to one.

The Coveo ML [Query Suggestion (QS)](https://docs.coveo.com/en/1015/) service uses the `documentPosition` value to judge the quality of suggested results (for example, if a query suggestion is followed by a click event on an item of rank 200, it's a bad suggestion and should be avoided in the future).

```json
{
  ...
  "documentPosition": 2,
  ...
}
```

### `documentUriHash` (string, deprecated)

> **Important**
>
> The `documentUriHash` property is deprecated.
> 
> Instead, you should provide the clicked [item](https://docs.coveo.com/en/210/)’s unique identifier by using the [`contentIDKey`](#contentidkey-string) and [`contentIDValue`](#contentidvalue-string) keys within the [`customData`](#click-event-customdata-key-value-pairs) property.
> 
> For example, you can use `permanentid` as the value for the `contentIDKey` [field](https://docs.coveo.com/en/200/) and assign the corresponding `permanentid` value of the clicked [item](https://docs.coveo.com/en/210/) to the `contentIDValue` [field](https://docs.coveo.com/en/200/), as follows:
> 
> ```json
{
  ...
  "customData":{
    "contentIDKey": "permanentid",
    "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
    ...
  },
  ...
}
```

The `@urihash` of the item that was clicked.
Maximum: 32 characters.

```json
{
  ...
  "documentUriHash": "xyhvGJJGRDM3OiG5",
  ...
}
```

### `language` (string)

The language of the search interface from which the click event originates.
Maximum: 256 characters.

This value must be an [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code, and it must match the first part of the `locale` value in the request body of the corresponding query to the Search API.

Coveo ML builds an independent CR submodel for each `language` value.

```json
{
  ...
  "language": "en",
  ...
}
```

### `searchQueryUid` (string)

The unique identifier of the query that caused the search interface to log a click event.

The `searchQueryUid` value must be the same as the `searchUid` value in the response of the corresponding search request to the Search API.

The Coveo ML ART and QS [models](https://docs.coveo.com/en/1012/) use `searchQueryUid` to relate click events to search events.

```json
{
  ...
  "searchQueryUid": "df60b2fb-c276-49ae-b704-2ee45609f3a6",
  ...
}
```

### `sourceName` (string)

The `@source` of the item that was clicked.
Maximum: 512 characters.

```json
{
  ...
  "sourceName": "AnswersCloud",
  ...
}
```

## Coveo ML-required request body properties

The following properties aren't required by the UA Write API when logging a click event, but they're required when using the Coveo ML service (otherwise, Coveo ML models won't function properly).

### `originLevel1` (string)

The name or identifier of the search interface from which the click event originates.
Maximum: 128 characters.

If `[originLevel1](https://docs.coveo.com/en/1337/)` isn't specified and the request is authenticated with a search token, the service tries to extract the `[searchHub](https://docs.coveo.com/en/1342/)` value from the access token that authenticated the request to log a search event (see [Set the Search Hub](https://docs.coveo.com/en/365#set-the-search-hub)).

When logging a search event, the `originLevel1` value must be the same as the `searchHub` value in the request body of the corresponding query to the Search API.

> **Important**
>
> Coveo ML models use the `originLevel1` value as a default filter field.
> These filters don't affect how the models learn, but they must be logged correctly for recommendations to work.
> When Coveo ML models make suggestions, items which don't meet the right filters are ignored (see [Get query suggestions - Troubleshooting](https://docs.coveo.com/en/1459#troubleshooting)).

```json
{
  ...
  "originLevel1": "ExternalSearch",
  ...
}
```

### `contentIDKey` (string)

> **Important**
>
> `contentIDKey` is a [`customData`](https://docs.coveo.com/en/2064#click-event-customdata-key-value-pairs) field, not a request body property.
> Coveo ML ART and CR models use this parameter to match the viewed page or component with the corresponding item in the [index](https://docs.coveo.com/en/204/).

The name of a field in the index that uniquely identifies the item.
Maximum: 128 characters.

A good practice is to use the [`permanentid`](https://docs.coveo.com/en/1913/) field.

```json
{
  ...
  "customData":{
    ...
    "contentIDKey": "permanentid",
    ...
  },
  ...
}
```

### `contentIDValue` (string)

> **Important**
>
> `contentIDValue` is a [`customData`](https://docs.coveo.com/en/2064#click-event-customdata-key-value-pairs) field, not a request body property.
> Coveo ML ART and CR models use this parameter to match the viewed page or component with the corresponding item in the index.

The value of the field selected as `contentIDKey`.
Maximum: 512 characters.

This is generally the `permanentid` value in the index.

```json
{
  ...
  "customData":{
    ...
    "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
    ...
  },
  ...
}
```

### `documentTitle` (string)

The title of the item that was clicked.
Maximum: 1024 characters.

The `documentTitle` value must be identical to the value of the `title` property of the corresponding item in the search request response.

The Coveo ML ART and CR models use `documentTitle` for debugging.

```json
{
  ...
  "documentTitle": "Coveo for Salesforce",
  ...
}
```

### `documentUrl` (string)

The URL of the item that was clicked.
Maximum: 1024 characters.

The `documentUrl` value must be identical to the value of the `uri` property of the corresponding item in the search request response.

The Coveo ML ART and CR models use `documentUrl` to identify items and for debugging.

```json
{
  ...
  "documentUrl": "https://docs.coveo.com/en/1243/",
  ...
}
```

### `rankingModifier` (string)

The ranking modifier that affected the clicked item.
Maximum: 128 characters.

> **Note**
>
> Although the `rankingModifier` property isn't required by the Usage Analytics (UA) Write API, it's required for the reports on the [**Visit Browser**](https://platform.cloud.coveo.com/admin/#/orgid/usage/visit/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/visit/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/visit/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/visit/)) page.

This corresponds to the `rankingModifier` property of the result item.

The `rankingModifier` property will eventually be leveraged by the Coveo ML service.

```json
{
  ...
  "rankingModifier": "Reveal ART",
  ...
}
```

### `userAgent` (string)

Information about the browser and operating system of the user who
caused the search interface to log a click event.
Maximum: 1024 characters.

> **Note**
>
> If the client performs HTTP requests directly against the UA Write API to log events (rather than performing those requests through a proxy server), the user's browser will typically include the correct information in the `User-Agent` request header.
> In this case, it's not necessary to specify a value for the `userAgent` request body property.

```json
{
  ...
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36",
  ...
}
```

These bot-generated events are flagged in the [**Device Category** dimension](https://docs.coveo.com/en/2948#device-category), but they aren't automatically blocked.
However, you can filter them out of reports as needed.

## Coveo ML-optional request body properties

The following properties aren't required by either the UA Write API or Coveo ML service when logging click events.
However, specifying values for these properties may improve the effectiveness of Coveo ML.

### `originLevel2` (string)

The name or identifier of the [tab](https://docs.coveo.com/en/1406/) from which the click event originates.
Maximum: 128 characters.

When logging a click event, the `[originLevel2](https://docs.coveo.com/en/1338/)` value must be identical to the `tab` value in the request body of the corresponding query to the Search API.
If there are no tabs in your search interface, you can reuse the `searchHub` value (in other words, you can use the same value for `originLevel1` and `originLevel2`).

> **Important**
>
> Coveo ML ART models use the `originLevel2` value as a default filter field.
> Filters don't affect how Coveo ML models learn, but they must be logged correctly for recommendations to work.
> When Coveo ML models make suggestions, items which don't meet the right filters are ignored.

```json
{
  ...
  "originLevel2": "All",
  ...
}
```

### `outcome` (integer from `-5` to `5`)

An indication of the quality of the outcome of this event.
A value of `-5` corresponds to the worst possible outcome, a value of `0` corresponds to a neutral outcome, and a value of `5` corresponds to the best possible outcome.

The `outcome` property will eventually be leveraged by the Coveo ML service.

```json
{
  ...
  "outcome": 0,
  ...
}
```

## Optional request body properties

The following properties are entirely optional when logging click events.
Although they're not leveraged by the Coveo ML service, specifying values for these properties can be useful for reporting.

### `anonymous` (Boolean)

Whether the interaction that caused the search interface to log a click event was triggered by an anonymous user.
The default value is `false`.

If the user is authenticated but wants to be anonymous, set `anonymous` to `true`.
The UA Write API won't extract the `name` and `userDisplayName`, if present, from the search token.
As long as you don't include their identity elsewhere in your request, the user will remain anonymous.

The `anonymous` value must be identical to the `isGuestUser` value of the corresponding search request to the Search API.
If an authenticated user wants to be anonymous, `isGuestUser` should be set to `true` when performing a query.

```json
{
  ...
  "anonymous": false,
  ...
}
```

### `documentAuthor` (string)

The author of the item that was clicked.
Maximum: 128 characters.

```json
{
  ...
  "documentAuthor": "John Doe",
  ...
}
```

### `documentUri` (string)

> **Important - Deprecated parameter**
>
> This parameter is deprecated and has no impact.
> 
> The `@uri` of the item that was clicked.

### `originContext` (string)

The origin of the event.
This is used to specify the deployment from which the user performs the action.
Maximum: 128 characters.
Suggested values are `Search`, `InternalSearch`,
`CommunitySearch`, or the `originLevel1` value.

```json
{
  ...
  "originContext": "CommunitySearch",
  ...
}
```

### `[originLevel3](https://docs.coveo.com/en/1339/)` (string)

The URL of the page that redirected the browser to the
search interface
from which the click event originates (that is, `document.referrer`). Maximum: 128 characters.
```json
{
  ...
  "originLevel3": "https://docs.coveo.com/en/0/coveo-documentation-for-developers",
  ...
}
```

### `queryPipeline` (string)

The name of the [query pipeline](https://docs.coveo.com/en/180/) which processed the query that
led to the
click event.
Maximum length of 128 characters.

If specified, the `queryPipeline` value takes precedence over the one defined in the search token [`pipeline`](https://docs.coveo.com/en/56#pipeline-string-optional) parameter.

If specified, the `queryPipeline` value must be the same as the `pipeline` value in the request body of the corresponding query to the Search API.

> **Important**
>
> When performing [A/B testing](https://docs.coveo.com/en/3255/), it's mandatory to include the `queryPipeline` in the usage analytics event.

```json
{
  ...
  "queryPipeline": "External Search",
  ...
}
```

### `splitTestRunName` (string)

The name of the [A/B test](https://docs.coveo.com/en/3255/) to run, if one is active.
Maximum: 128 characters.

```json
{
  ...
  "splitTestRunName": "splitTest",
  ...
}
```

### `splitTestRunVersion` (string)

The version of the A/B test to run, if one is active.
Maximum: 128 characters.

```json
{
  ...
  "splitTestRunVersion": "splitTestRunAlpha",
  ...
}
```

### `trackingId` (string)

The value to identify which web property an event is related to.
This is a human-readable name you can use when sending analytics events.

```json
{
  ...
  "trackingId": "online_store",
  ...
}
```

### `userDisplayName` (string)

The display name of the user performing the click event.
Maximum: 128 characters.

If `userDisplayName` isn't specified and the request is authenticated with a search token, the service tries to extract the `userdisplayName` value from the access token that authenticated the request to log a click event.

```json
{
  ...
  "userDisplayName": "Alice",
  ...
}
```

### `username` (string)

The name of the [user](https://docs.coveo.com/en/250/) [security identity](https://docs.coveo.com/en/240/) which
caused the search interface to log a click event.
Maximum: 128 characters.
This can only be specified when authenticated with an API key that was created using the **Authenticated search** [template](https://docs.coveo.com/en/1718#api-key-templates) or an [OAuth2 token](https://docs.coveo.com/en/1369/) with the privilege to [impersonate](https://docs.coveo.com/en/2737/) users (that is, the **Allowed** access level on the [**Impersonate** domain](https://docs.coveo.com/en/1707#impersonate-domain-analytics)).

> **Important**
>
> A private API key or an OAuth2 token with the privilege to impersonate users shouldn't be exposed publicly.

If `username` isn't specified and the request is authenticated with a search token, the service tries to extract the `username` value from the access token that authenticated the log search event request.
If this fails, `username` is left blank.

If this isn't specified and the request is authenticated with an API key, `username` is set to `anonymous`.

```json
{
  ...
  "username": "alice.smith@example.com",
  ...
}
```

## Click event `customData` (key-value pairs)

These are custom key-value pairs which can contain all of the user-defined [dimensions](https://docs.coveo.com/en/258/) and their values, and which can be used for reporting or learning.

* The `customData` section must be valid JSON.

* When possible, use a string as the value.

* The value can be any valid JSON, but it's handled as string over [Coveo Analytics](https://docs.coveo.com/en/182/), and the string conversion could result in the alteration of the original JSON.
Keys may only contain alphanumeric or underscore characters, and all spaces in the keys are replaced with underscores.
Any uppercase characters in the keys are converted to lowercase characters.

**Examples**

* `"key" : "value"` → This is the recommended format for [Coveo Analytics](https://docs.coveo.com/en/182/), which renders the string as `"value"` and makes it usable as any other string [dimension](https://docs.coveo.com/en/258/) type.

* `"key" : [ "value_1", "value_2" ]` → This becomes the string `"[ "value_1", "value_2" ] "` within [Coveo Analytics](https://docs.coveo.com/en/182/).
Although it's harder to use for reporting, this value could still be useful (for example, when using the filter `"contains"` type).

* We recommend that you [create your custom dimension](https://docs.coveo.com/en/1522/) before adding `customData`.

* Any [field](https://docs.coveo.com/en/200/) beginning with `context_` will be used by [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) as user [context](https://docs.coveo.com/en/1345/) to learn and provide boosts to contextually relevant [items](https://docs.coveo.com/en/210/).

* When logging click events, two custom data [fields](https://docs.coveo.com/en/200/) are required for certain [Coveo ML](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) to function correctly: [`contentIDKey`](https://docs.coveo.com/en/2064#contentidkey-string) and [`contentIDValue`](https://docs.coveo.com/en/2064#contentidvalue-string).

The [Coveo ML](https://docs.coveo.com/en/188/) [Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/1013/) and [Content Recommendation (CR)](https://docs.coveo.com/en/1016/) [models](https://docs.coveo.com/en/1012/) use these custom data [fields](https://docs.coveo.com/en/200/) to locate the clicked [item](https://docs.coveo.com/en/210/) in the [index](https://docs.coveo.com/en/204/).

The [Query Suggestion (QS)](https://docs.coveo.com/en/1015/) and [Predictive Query Suggestion (PQS)](https://docs.coveo.com/en/m1ol5526/) [models](https://docs.coveo.com/en/1012/) don't use these [fields](https://docs.coveo.com/en/200/) directly, but they do use click events to assess the quality of their suggested results.
These click events must include the `contentIdKey` and `contentIdValue` custom data [fields](https://docs.coveo.com/en/200/) to be considered valid.

> **Important**
>
> Previously, the [QS](https://docs.coveo.com/en/1015/) and [PQS](https://docs.coveo.com/en/m1ol5526/) [models](https://docs.coveo.com/en/1012/) used the `documentURIhash` property to assess the quality of their suggested results.
> With its deprecation, these [models](https://docs.coveo.com/en/1012/) instead use the number of click events generated by a suggestion to assess its quality.
> 
> If your [QS](https://docs.coveo.com/en/1015/) or [PQS](https://docs.coveo.com/en/m1ol5526/) [model](https://docs.coveo.com/en/1012/) isn't generating suggestions, it could be because the click events are still including `documentURIhash` rather than `contentIdKey` and `contentIdValue`, and aren't considered valid.
> You can check the [**Data Health**](https://platform.cloud.coveo.com/admin/#/orgid/usage/health/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/health/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/health/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/health/)) page in the [Coveo Administration Console](https://docs.coveo.com/en/183/) to see if your events are reporting any errors.

`contentIDKey` is the name of a [field](https://docs.coveo.com/en/200/) in the [index](https://docs.coveo.com/en/204/) that uniquely identifies the [item](https://docs.coveo.com/en/210/).
This is typically [`permanentid`](https://docs.coveo.com/en/1913/), and `contentIDValue` is the value of the [field](https://docs.coveo.com/en/200/) selected as `contentIDKey`.
These [fields](https://docs.coveo.com/en/200/) can be found in the search request response, under the `raw.permanentid` of the clicked [item](https://docs.coveo.com/en/210/) in the result list.

```json
{
  ...
  "customData":{
    "contentIDKey": "permanentid",
    "contentIDValue": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
    "documentTitle": "Coveo for Salesforce",
    "documentURL": "https://docs.coveo.com/en/1243/"
  },
  ...
}
```