The generated API clients are a work in progress, you can also find our stable clients on the Algolia documentation.

Skip to main content
API docs by Redocly

Insights API (1.0.0)

Download OpenAPI specification:Download

The Algolia Insights API lets you collect events related to your search and discovery experience. Events represent 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

Events represent user interactions with your website or app. They include details like the event's name, type, a timestamp or a user token.

Send events

Send a list of events to the Insights API.

You can include up to 1,000 events in a single request, but the request body must be smaller than 2 MB.

Authorizations:
(appIdapiKey)
Request Body schema: application/json
required
Array of Clicked object IDs after search (object) or Converted object IDs after search (object) or Clicked object IDs (object) or Converted object IDs (object) or Clicked filters (object) or Converted filters (object) or Viewed object IDs (object) or Viewed filters (object) (EventsItems) [ 1 .. 1000 ] items

List of click and conversion events.

An event is an object representing a user interaction. Events have attributes that describe the interaction, such as an event name, a type, or a user token. Some attributes require other attributes to be declared, and some attributes can't be declared at the same time.

All events must be valid, otherwise the API returns an error.

Array ([ 1 .. 1000 ] items)
One of
eventName
required
string (eventName) [ 1 .. 64 ] characters

Can contain up to 64 ASCII characters.

Consider naming events consistently—for example, by adopting Segment's object-action framework.

eventType
required
string (ClickEvent)
Value: "click"
index
required
string (index)

Name of the Algolia index.

objectIDs
required
Array of strings (objectIDs) [ 1 .. 20 ] items

List of object identifiers for items of an Algolia index.

positions
required
Array of integers (positions) [ 1 .. 20 ] items >= 1

Position of the clicked objects in the search results.

The first search result has a position of 1 (not 0). You must provide 1 position for each objectID.

queryID
required
string (queryID) = 32 characters [0-9a-f]{32}

Unique identifier for a search query.

The query ID is required for events related to search or browse requests. If you add clickAnalytics: true as a search request parameter, the query ID is included in the API response.

userToken
required
string (userToken) [ 1 .. 128 ] characters [a-zA-Z0-9_=/+-]{1,128}

Anonymous or pseudonymous user identifier.

Note: Never include personally identifiable information in user tokens.

timestamp
integer <int64> (timestamp)

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.

Responses

Request samples

Content type
application/json
Example
{
  • "events": [
    ]
}

Response samples

Content type
application/json

Success indicates that the Insights API received the events correctly, and that event properties are formatted correctly. Success doesn't imply that the event can be used by any Algolia feature. For example, the Insights API doesn't check if the index name you provided exists, or if the object IDs exist in your index.

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