API Reference / REST API / Insights REST API

The Algolia Insights API lets you collect events (user interactions) with your search and discovery experience.

Sending events prepares you to use these features:

Different features require different types and numbers of events. For more information, see Send Insights events.

Host

The base URL of the Algolia Insights API is:

1
https://insights.algolia.io

All API requests must use HTTPS.

Authentication

To authenticate your requests, add these headers:

  • X-Algolia-Application-Id: your Algolia application ID
  • X-Algolia-API-Key: your API key with search access control list permission.

Find your application ID and API key in the Algolia dashboard.

Alternatively, you can add your credentials as query parameters:

1
https://insights.algolia.io/1/events?x-algolia-application-id={YourApplicationId}&x-algolia-api-key={YourAPIKey}

Response

The response of the Insights API is a JSON object with the following content:

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

The Insights API uses the conventional HTTP status codes:

200 The request was successful
4xx Your request has at least one issue, such as a missing or invalid parameter
5xx The Insights API servers have an issue

Event properties

The basic shape of an event object is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  // Event type: click, conversion, or view
  "eventType": "click",
  // Name for the specific event
  "eventName": "Clicked Search Result",
  // Events are related to items from an Algolia index
  "index": "prod_ecommerce_EN",
  // Pseudonymous or anonymous user identifier
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx",
  // Optional: time of the event. By default the current time is used.
  "timestamp": "1673636676",
  // For search and browse events only: a unique identifier of the search query leading to this event
  "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
  // List of objectIDs the user interacted with. Can't be used with `filters`
  "objectIDs": ["item-1"],
  // List of filters the user interacted with. Can't be used with `objectIDs`
  // "filters": "",
  // For search and browse events only: the position of the `objectID` in the search results.
  "positions": [1],
}

Not all event types need all properties. Algolia’s libraries include methods for sending specific events so that you don’t have to include every property manually.

Events endpoints

Quick Reference

Verb Path Method

POST

/1/events

Send events

Send events

A

Path: /1/events
HTTP Verb: POST

Description:

Send a list of events to the Insights API.

You can send up to 1,000 events in a single request.

All events must be valid. If one or more events are invalid, the API returns the error: 422: Unprocessable Entity. For more information, see Validate your events.

The request body size must be less than 2 MB.

Parameters:

eventType
type: click | conversion | view
Required

The type of the event, either click, conversion, or view.

Related: API client methods

eventName
type: string
pattern: [\x20-\x7E]{1,64}
Required

The name of the specific event.

Format: 1-64 ASCII characters, except control characters.

To maximize the impact of your events, you should use consistent event names and consistent formatting—for example, “Product Added To Cart” (always in title case).

For example, you can adopt Segment’s object-action framework.

index
type: string
Required

The name of the Algolia index.

Format: same as the index name used by the search engine.

userToken
type: string
pattern: [A-Za-z0-9_-=]{1,128}
Required

A pseudonymous or anonymous user identifier.

Never include personal identifiable information in user tokens.

Related: user token

timestamp
type: int64
default: now()
Optional

The time of the event in milliseconds in Unix epoch time. By default, the Insights API uses the time it receives an event as its timestamp.

If you’re not sending events in real time—for example, if you’re doing backend search, it’s important to set correct timestamps. If you’re sending events in batches and you’re not including a timestamp, all events will have the same timestamp.

The Algolia Insights API accepts events from up to 4 days in the past. Timestamps for click and conversion events must be within 1 hour of the corresponding search or browse request.

queryID
type: string
pattern: [a-f0-9]{32}
Optional

A unique identifier for a search query.

A queryID is required for events related to search or browse requests.

If you add clickAnalytics: true as a search request parameter, the queryID is included in the API response.

Related: Keep track of query IDs

objectIDs
type: array
items: string
Optional

An array of object identifiers for items of an Algolia index.

You can include up to 20 objectID.

A single event must not include both objectIDs and filters.

filters
type: array
items: string
pattern: ${attr}:${value}
Optional

An array of facet filters.

You can include up to 10 filters.

Format: ${attribute}:${value}—for example, brand:apple. Each facet filter string must be URL-encoded, such as, "discount:10%25".

A single event must not include both objectIDs and filters.

positions
type: array
items: uint
Optional

The position of the clicked objects in the search results. This property is required for click events with queryID.

You must provide one position for each objectID.

Algolia uses this parameter to calculate the average click position.

The position is absolute, and not relative, to any results page. For example, if there are 10 results per page, the position of the third record of the second results page is 13. Since page starts at 0, you can use the following formula: $positionOnPage + $page * hitsPerPage.

If you’re using InstantSearch, you can get the position through the hit.__position attribute.

Errors:

  • 422: Unprocessable Entity. At least one event in the batch is invalid. Only the first encountered error is reported.

  • 413: Request Entity Too Large. The size of the body exceeds 2 MB.
  • 401: Unauthorized. The credentials (Algolia application ID and API key) are either missing, incorrect, or don’t have the search ACL.

Example

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

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 --request POST \
     --url https://insights.algolia.io/1/events \
     --header "X-Algolia-Api-Key: ${SEARCH_API_KEY}" \
     --header "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --header "Content-Type: application/json" \
     --data-binary '{
          "events": [
            {
              "eventType": "click",
              "eventName": "Product Clicked",
              "index": "products",
              "userToken": "user-123456",
              "timestamp": 1674820985415,
              "objectIDs": ["9780545139700", "9780439784542"],
              "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
              "positions": [7, 6]
            },
            {
              "eventType": "view",
              "eventName":"Viewed Product Detail Page",
              "index": "products",
              "userToken": "user-123456",
              "timestamp": 1674820985415,
              "objectIDs": ["9780545139700", "9780439784542"]
            },
            {
              "eventType": "conversion",
              "eventName": "Purchased Product",
              "index": "products",
              "userToken": "user-123456",
              "timestamp": 1674820985415,
              "objectIDs": ["9780545139700", "9780439784542"],
              "queryID": "43b15df305339e827f0ac0bdc5ebcaa7"
            }
          ]
        }'

If the request is successful, the Insights API responds with:

1
2
3
4
{
  "status": 200,
  "message": "OK"
}
Did you find this page helpful?