Insights REST API

You can reach the Insights API endpoint at https://insights.algolia.io.

The Insights API lets you push a collection of events related to your product’s use. Sending those events is a required step for using several Algolia features:

Click and conversion analytics
A/B testing
Personalization
Dynamic Re-ranking
Algolia Recommend

Each feature has a minimum number of required events.

Authentication

The API requires the application ID and API key to be passed through the following headers:

X-Algolia-Application-Id: the application ID.
X-Algolia-API-Key: the authentication token.

Optionally, those parameters (case sensitive) are also accepted as URL parameters.

The X-Algolia-API-Key must have the search access control list, and you must enable click analytics on your account.

Validation error

If there is an error, the Insights API will return a payload in the following format:

Copy

1
2
3
4
{
  "status": 123,
  "message": "The error message"
}

Limitations

Insights requires a minimum number of events (depending on which features are being used)
For click analytics, there is a one-hour conversion window for click and conversion events. This means a click or conversion event timestamp must be within one hour of the corresponding search event.
The Insights API accepts events up to four days in the past.

Insights

Quick Reference

Verb	Path	Method
POST	/1/events	Push events

Push events

Path: /1/events
HTTP Verb: POST

Description:

This command pushes an array of events to the Insights API.

An event is

an action: eventName
performed in a context: eventType
at some point in time provided: timestamp
by an end user: userToken
on something: index

Notes:

The number of events that can be sent in a single request is limited to 1000.
To be accepted, all events sent must be valid.
The size of the body must be less than 2 MB.
When an event is tied to an Algolia search, it must also provide a queryID. If that event is a click, their absolute positions should also be passed.
We consider that an index provides access to 2 resources: objects and filters. An event can only interact with a single resource type, but not necessarily on a single item. As such an event will accept an array of objectIDs or filters.

Parameters:

`eventType`	type: string Required An `eventType` can be a `click`, a `conversion`, or a `view`.
`eventName`	type: string Required A user-defined string used to categorize events. Format: any ASCII character, except control points with a length between 1 and 64.
`index`	type: string Required Name of the targeted index. Format:: same as the index name used by the search engine.
`userToken`	type: string Required A user identifier. Depending if the user is logged-in or not, several strategies can be used from a sessionId to a technical identifier. You should always send pseudonymous or anonymous userTokens. Format: [a-zA-Z0-9_-=/+]{1,128}
`timestamp`	type: int64 default: now() Optional Time of the event expressed in milliseconds since the Unix epoch.
`queryID`	type: string Optional Algolia `queryID`. This is required when an event is tied to a search. It can be found in the Search API results response.
`objectIDs`	type: array Optional An array of index `objectID`. Limited to 20 objects. An event can’t have both `objectIDs` and `filters` at the same time.
`filters`	type: array Optional An array of facet filters. Limited to 10 filters. Format: ${attribute}:${value}, like `brand:apple`. Each facet filter string should be URL-encoded, for example `"discount:10%25"`. An event can’t have both `objectIDs` and `filters` at the same time.
`positions`	type: []int Optional Position of the click in the list of Algolia search results. This field is required if a `queryID` is provided. One position must be provided for each `objectID`. The position value must be absolute, not relative, to the result page. For example, when clicking on the third record of the second results page, assuming 10 results per page, the position should be 13. Since `page` starts at 0, you can use the following formula: `$positionOnPage + $page * hitsPerPage`. Note: For InstantSearch implementations, this position is available through the `hit.__position` attribute Only include this parameter when sending `click` events.

Errors:

422: Unprocessable Entity. At least one event in the batch was invalid; the endpoint only provides a message for the first error encountered.
413: Request Entity Too Large. The size of the body exceeds 2 MB.
401: Unauthorized. The credentials (AppID, API Key) are either missing, incorrect or do not have the click analytics enabled feature.

Example

The following examples send three events for the same user: one click event, one view event, and one conversion event.

Copy
curl -X POST \
https://insights.algolia.io/1/events \
-H 'x-algolia-api-key: ${SEARCH_API_KEY}' \
-H 'x-algolia-application-id: ${APPLICATION_ID}' \
-H "Content-Type: application/json" \
-d '{
    "events": [
        {
          "eventType": "click",
          "eventName": "Product Clicked",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1666627207967,
          "objectIDs": ["9780545139700", "9780439784542"],
          "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
          "positions": [7, 6]
        },
        {
          "eventType": "view",
          "eventName":"Product Detail Page Viewed",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1666627207967,
          "objectIDs": ["9780545139700", "9780439784542"]
        },
        {
          "eventType": "conversion",
          "eventName": "Product Purchased",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1666627207967,
          "objectIDs": ["9780545139700", "9780439784542"],
          "queryID": "43b15df305339e827f0ac0bdc5ebcaa7"
        }
      ]
    }'

When the query is successful, the HTTP response is a 200 OK.

Copy

1
2
3
4
{
  "status": 200,
  "message": "OK"
}

Did you find this page helpful?