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

Typically, whenever a user interacts with a [search interface](https://docs.coveo.com/en/2741/) in a way that needs to be recorded, but that isn't a search, click, or view event, the search interface logs a custom event.
For example, a custom event can be logged when the user toggles the result list layout or changes their user preferences.

This article provides guidelines for performing HTTP requests against the [Usage Analytics (UA) Write API](https://docs.coveo.com/en/18/) to properly log custom 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 custom event, make a POST request to

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

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/custom
```

> **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/) service 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/custom HTTP/1.1
​
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

Payload:

```json
{
  "anonymous": false,
  "eventType": "facet",
  "eventValue": "facetSearch",
  "language": "en",
  "originLevel1": "ExternalSearch",
  "originLevel2": "All",
  "clientId": "489aa3e3-aed2-4563-8e81-62bb73178a56",
}
```

## Required request body properties

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

### `eventType` (string)

The custom event type.
Maximum: 128 characters.

```json
{
  ...
  "eventType": "facet",
  ...
}
```

### `eventValue` (string)

The custom event value.
Maximum: 128 characters.

```json
{
  ...
  "eventValue": "facetSearch",
  ...
}
```

### `language` (string)

The language of the search interface from which the custom 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",
  ...
}
```

## ML-required request body properties

By default, the [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Content Recommendation (CR)](https://docs.coveo.com/en/1016/) [model](https://docs.coveo.com/en/1012/) doesn't feed on custom events.
However, it's possible to configure an CR model to feed on custom event data.

Contact your Coveo Customer Success Manager (CSM) or [Coveo Support](https://connect.coveo.com/s/case/Case/Default) for more information.

## Optional request body properties

The following properties are entirely optional when logging custom 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 custom 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,
  ...
}
```

### `lastSearchQueryUid` (string)

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

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

```json
{
  ...
  "lastSearchQueryUid": "7bfc652a-9dea-4811-b3f9-6d24345c37ce"
  ...
}
```

### `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`,
or `CommunitySearch`.

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

### `originLevel1` (string, optional)

The name or identifier of the search interface from which the custom 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 custom event (see [Set the Search Hub](https://docs.coveo.com/en/365#set-the-search-hub)).

When logging a custom 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",
  ...
}
```

### `originLevel2` (string)

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

When logging a custom 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",
  ...
}
```

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

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

### `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.

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

### `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 custom 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 custom 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 custom 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",
  ...
}
```

## Custom 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`.

```json
{
  ...
  "customData":{
    "facetId": "@objecttype",
    "facetTitle": "Type"
  },
  ...
}
```