API reference / Insights API

Insights API

The Algolia Insights API lets you collect events related to your search and discovery experience. Events are actions that users take on your app or website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience.

Events enable these features:

For more information about events, see Get started with click and conversion events.

Base URL

The base URL of the Algolia Insights API is:

Copy 
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:

Copy 
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:

Copy 
1
2
3
4

{
  "status": 123,
  "message": "The status message"
}

The Insights API uses the conventional HTTP status codes:

Code Description
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 shape of an event depends on the type of event you’re sending:

An incorrectly shaped event will still be accepted, for example, when a required property is omitted, but it may not be used for the intended features.

See the parameters of the Send events endpoint for an overview of all event properties.

Algolia’s libraries include methods for sending specific events so that you don’t have to include every property manually.

Guides Get started with click and conversion events
Insights methods in the API clients
Send Insights events with InstantSearch
Send Insights events with Autocomplete

Click events

Clicked object IDs

Copy 
1
2
3
4
5
6
7
8
9

{
  "eventType": "click", // Required
  "eventName": "Items Clicked", // Required
  "index": "prod_ecommerce_EN", // Required
  "objectIDs": ["item-1"], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Copy 
1
2
3
4
5
6
7
8
9
10
11

{
  "eventType": "click", // Required
  "eventName": "Items Clicked After Search", // Required
  "index": "prod_ecommerce_EN", // Required
  "queryID": "43b15df305339e827f0ac0bdc5ebcaa7", // Required
  "objectIDs": ["item-1", "item-2"], // Required
  "positions": [3, 7], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Clicked filters

Copy 
1
2
3
4
5
6
7
8
9

{
  "eventType": "click", // Required
  "eventName": "Filters Clicked", // Required
  "index": "prod_ecommerce_EN", // Required
  "filters": ["color:red"], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Conversion events

Converted object IDs

Copy 
1
2
3
4
5
6
7
8
9

{
  "eventType": "conversion", // Required
  "eventName": "Items Converted", // Required
  "index": "prod_ecommerce_EN", // Required
  "objectIDs": ["item-1"], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Copy 
1
2
3
4
5
6
7
8
9
10

{
  "eventType": "conversion", // Required
  "eventName": "Items Converted After Search", // Required
  "index": "prod_ecommerce_EN", // Required
  "queryID": "43b15df305339e827f0ac0bdc5ebcaa7", // Required
  "objectIDs": ["item-1"], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Converted filters

Copy 
1
2
3
4
5
6
7
8
9

{
  "eventType": "conversion", // Required
  "eventName": "Filters Converted", // Required
  "index": "prod_ecommerce_EN", // Required
  "filters": ["size:large"], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Add-to-cart events

Added object IDs to cart

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "eventType": "conversion", // Required
  "eventSubtype": "addToCart", // Required
  "eventName": "Products Added to Cart", // Required
  "index": "prod_ecommerce_EN", // Required
  "objectIDs": ["item-1", "item-10"], // Required
  "objectData": [
    {
      "price": 15.00, // Optional
      "discount": 5.00, // Optional
      "quantity": 10, // Optional
    },
    {
      "price": 99.99,
    }
  ], // Optional
  "value": 249.99, // Optional
  "currency": "USD", // Required if objectData.price or value is provided
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "eventType": "conversion", // Required
  "eventSubtype": "addToCart", // Required
  "eventName": "Products Added to Cart After Search", // Required
  "index": "prod_ecommerce_EN", // Required
  "queryID": "43b15df305339e827f0ac0bdc5ebcaa7", // Required
  "objectIDs": ["item-1"], // Required
  "objectData": [
    {
      "price": 29.99, // Optional
      "discount": 10.00, // Optional
      "quantity": 2 // Optional
    }
  ], // Optional
  "value": 59.98, // Optional
  "currency": "USD", // Required if objectData.price or value is provided
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Purchase events

Purchased object IDs

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "eventType": "conversion", // Required
  "eventSubtype": "purchase", // Required
  "eventName": "Products Purchased", // Required
  "index": "prod_ecommerce_EN", // Required
  "objectIDs": ["item-1"], // Required
  "objectData": [
    {
      "price": 15.00, // Optional
      "discount": 5.00, // Optional
      "quantity": 10, // Optional
    }
  ], // Optional
  "value": 150.00, // Optional
  "currency": "EUR", // Required if objectData.price or value is provided
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "eventType": "conversion", // Required
  "eventSubtype": "purchase", // Required
  "eventName": "Products Purchased After Search", // Required
  "index": "prod_ecommerce_EN", // Required
  "objectIDs": ["item-1", "item-2"], // Required
  "objectData": [
    {
      "queryID": "43b15df305339e827f0ac0bdc5ebcaa7", // Optional (required for objects that were purchased as the result of a query)
      "price": 29.99, // Optional
      "discount": 10.00, // Optional
      "quantity": 2 // Optional
    },
    {
      "price": 18.50, // Optional
    }
  ], // Required (at least one objectData item including a queryID is required)
  "value": 78.48, // Optional
  "currency": "EUR", // Required if objectData.price or value is provided
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

View events

Viewed object IDs

Copy 
1
2
3
4
5
6
7
8
9

{
  "eventType": "view", // Required
  "eventName": "Items Viewed", // Required
  "index": "prod_ecommerce_EN", // Required
  "objectIDs": ["item-1"], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Viewed filters

Copy 
1
2
3
4
5
6
7
8
9

{
  "eventType": "view", // Required
  "eventName": "Filters Viewed", // Required
  "index": "prod_ecommerce_EN", // Required
  "filters": ["color:red", "discount:10%25"], // Required
  "userToken": "anonymous-xxxxxx-xx-xxx-xxxxxx", // Required
  "authenticatedUserToken": "user-xxxxxx-xx-xxx-xxxxxx", // Optional
  "timestamp": 1673636676000, // Optional
}

Sending this event is useful for:

Events endpoints

Quick reference

Verb Path Method

POST

/1/events

Send events

Send events

A

Path: /1/events
HTTP Verb: POST
Required API Key: any key with the search ACL

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:

Parameter Description
eventType
type: click | conversion | view
Required

Type of the event, either click, conversion, or view.

See also: Event types
eventSubtype
type: addToCart | purchase
Optional

Subtype of the event. For conversion events either addToCart, or purchase. For all other events it should be omitted.

Used to enable Algolia to provide more detailed analytics reports.
eventName
type: string
pattern: [\x20-\x7E]{1,64}
Required

Name of the specific event.

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

To maximize the impact of your events, 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

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,129}
Required

Anonymous user identifier.

See also: User Token
authenticatedUserToken
type: string
pattern: [A-Za-z0-9_=+/-]{1,129}
Optional

Pseudonymous identifier for authenticated users.

Never include personally identifiable information in user tokens.

See also: User Token
timestamp
type: int64
default: now()
Optional

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.

  • All events: timestamp may be up to 4 days in the past.
  • In addition, for events with queryID: timestamp must be within 1 hour of the corresponding search or browse request.
queryID
type: string
pattern: [a-f0-9]{32}
Optional

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.

See also: Keep track of query IDs
objectIDs
type: array
items: string
Optional

List 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.
objectData
type: array
items: ObjectData
Optional

Extra information about the records involved in the event—for example, to add price and quantities of purchased products.

If provided, must be the same length as objectIDs.
filters
type: array
items: string
pattern: ${attr}:${value}
Optional

List of facet filters.

You can include up to 10 filters.

Format: ${attribute}:${value}—for example, brand:apple. Both the attribute and value in each facet filter must be URL-encoded individually and separated by a :, such as, "discount:10%25".

A single event must not include both objectIDs and filters.
positions
type: array
items: uint
Optional

Positions of the clicked objects in the search results. This property is required for click events with queryID. The first search result has a position of 1 (not 0).

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.
value
type: number | string
Optional

The monetary value of the event, measured in currency. For example, the total value of a purchase.
currency
type: string
Optional

If you include pricing information in the objectData parameter or provide value, you must also specify the currency as ISO-4217 currency code, such as USD or EUR.

ObjectData

Parameter Description
queryID
type: string
Optional

ID of the query that this specific record is attributable to. Used to track purchase events with multiple items originating from different searches.

See also: Keep track of query IDs
price
type: number | string
Optional

The price of the item. This should be the final price, inclusive of any discounts in effect.
quantity
type: number
default:
Optional

The quantity of the purchased or added-to-cart item. The total value of a purchase is the sum of quantity multiplied with the price for each purchased item.
discount
type: number | string
Optional

Absolute value of the discount in effect for this object, measured in currency.

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:

A

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

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
37
38
39
40
41
42
43
44

curl 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": 1714049553350,
              "objectIDs": ["9780545139700", "9780439784542"],
              "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
              "positions": [7, 6]
            },
            {
              "eventType": "view",
              "eventName":"Product Details Viewed",
              "index": "products",
              "userToken": "user-123456",
              "timestamp": 1714049553350,
              "objectIDs": ["9780545139700", "9780439784542"]
            },
            {
              "eventType": "conversion",
              "eventSubtype": "addToCart",
              "eventName": "Product Added To Cart",
              "index": "products",
              "userToken": "user-123456",
              "timestamp":  1714049553350,
              "objectIDs": ["9780545139700", "9780439784542"],
              "objectData": [{
                "price": "1.25",
                "quantity": 2
              }, {
                "price": "4.95",
                "quantity": 1
              }],
              "currency": "USD",
              "queryID": "43b15df305339e827f0ac0bdc5ebcaa7"
            }
          ]
        }'

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

Copy 
1
2
3
4

{
  "status": 200,
  "message": "OK"
}

User token endpoints

Quick reference

Verb Path Method

DELETE

/1/usertokens/{userToken}

Delete a user token

Delete a user token

A

Path: /1/usertokens/{userToken}
HTTP Verb: DELETE
Required API Key: any key with the deleteObject ACL

Description:

Delete all events related to the specified user from event metrics and analytics data. The deletion is asynchronous and can take several minutes.

To delete a personalization user profile associated with this user token, see Delete a user profile

On success the endpoint returns the HTTP code 204.

Parameters:

Parameter Description
userToken
type: string
pattern: [A-Za-z0-9_=+/-]{1,129}
Required

Anonymous user identifier.

See also: User Token

Errors:

  • 422: Unprocessable Entity. The userToken is in an invalid format.

  • 429: Too Many Requests. Rate limit reached. Check the headers X-Ratelimit-Limit and X-Ratelimit-Reset to know the rate limit and its reset time.

  • 401: Unauthorized. The credentials (Algolia application ID and API key) are either missing, incorrect, or don’t have the deleteObject ACL.

Did you find this page helpful?