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
required
Array of Clicked object IDs after search (object) or Added to cart object IDs after search (object) or Purchased object IDs after search (object) or Converted object IDs after search (object) or Clicked object IDs (object) or Purchased object IDs (object) or Added to cart 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.

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

Array ([ 1 .. 1000 ] items)
One of
eventName
required
string (eventName) [ 1 .. 64 ] characters [\x20-\x7E]{1,64}

The name of the event, 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)

The name of an Algolia index.

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

The object IDs of the records that are part of the event.

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

The position of the clicked item 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 .. 129 ] characters [a-zA-Z0-9_=/+-]{1,129}

An anonymous or pseudonymous user identifier.

Note: Never include personally identifiable information in user tokens.

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

An identifier for authenticated users.

Note: Never include personally identifiable information in user tokens.

timestamp
integer <int64> (timestamp)

The timestamp 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"
}

User tokens

Delete events related to a specific user token.

Delete user token.

Delete all events related to a certain user token from events metrics and analytics. To delete a personalization user profile, see Delete a user profile.

Authorizations:
(appIdapiKey)
path Parameters
userToken
required
string [ 1 .. 129 ] characters [a-zA-Z0-9_=/+]{1,129}
Example: test-user-1

The user token for which to delete all associated events.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": 0
}