API Reference / REST API / Insights REST API
Apr. 01, 2019

Insights REST API

Overview

The Insights API endpoint can be reached 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

The Insights API is only available to Enterprise customers.

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:

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

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 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 char, 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. It 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: []uint
Optional

Position of the click in the list of Algolia search results.

This field is required if a queryID is provided. One position should be provided for each objectID

It applies only for click events.

Errors:

  • 422: Unprocessable Entity. At least an 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:

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": "view",
          "eventName": "landing after a marketing campaign",
          "timestamp": 1529055974,
          "index": "products",
          "userToken": "ab6b88197c7941ee",
          "filters": ["brand:apple"]
        },
        {
          "eventType": "click",
          "eventName": "add to cart from search",
          "timestamp": 1521710906,
          "index": "products",
          "userToken": "67e91a90983a4cd3",
          "objectIDs": ["12345", "67890"],
          "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
          "positions": [17, 19]
        },
        {
          "eventType": "conversion",
          "eventName": "search",
          "timestamp": 1528364634,
          "index": "products",
          "userToken": "1b9e25dc454f4916",
          "objectIDs": ["12345", "7890a"],
          "queryID": "43b15df305339e827f0ac0bdc5ebcaa7"
        }
      ]
    }'

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

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

Did you find this page helpful?