API Reference / REST API / Insights REST API

Insights REST API

Overview

The Insights API endpoint can be reached via https://insights.algolia.io.

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

  • Click analytics
  • A/B Testing
  • Personalization
  • Dynamic Re-Ranking

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 needs to have the search ACL.

You also need to have click analytics enabled on your account.

Validation Error

In case of error the Insights API will return a payload in the following format:

Copy 
1
2
3
4

{
  “status”: 123,
  “message”: ”The error message”
}

Limitations

For click analytics, there is a one hour conversion window for click and conversion events. This means that a click or conversion event timestamp must be within one hour of the corresponding search event to be taken into account.

The Insights API currently accepts events up to 4 days in the past.

Insights

Quick Reference

Verb Path Method

POST

/1/events

Push events

Push events

A

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 at the same time is limited to 1000.
  • To be accepted, all events sent must be valid.
  • 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,64}
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 filters. Limited to 10 filters.

Format: ${attribute}:${value}, like brand:apple.

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. Usually, since page starts at 0, you can use the following formula: $positionOnPage + ($page - 1) * hitsPerPage.

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.
  • 401: Unauthorized. The credentials (AppID, API Key) are either missing, incorrect or do not have the click analytics enabled feature.

Example:

A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

curl -X POST \
https://insights.algolia.io/1/events \
-H 'x-algolia-api-key: ${ADMIN_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": 1529055974,
          "objectIDs": ["9780545139700", "9780439784542"],
          "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
          "positions": [7, 6]
        },
        {
          "eventType": "view",
          "eventName":"Product Detail Page Viewed",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1521710906,
          "objectIDs": ["9780545139700", "9780439784542"]
        },
        {
          "eventType": "conversion",
          "eventName": "Product Purchased",
          "index": "products",
          "userToken": "user-123456",
          "timestamp": 1528364634,
          "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?