Send events

Sends 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.

POST /1/events

curl

cURL

curl --request POST \
  --url https://insights.us.algolia.io/1/events \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
  --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
  --data '{"events":[{"eventName":"Products Clicked","eventType":"click","index":"test-index","userToken":"anonymous-user-1","authenticatedUserToken":"user-1","objectIDs":["object-1"],"positions":[1],"queryID":"7dfe2ada7bca48bdd0629649df0bee07"}]}'

200

Success

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

Required ACL: search

Authorizations

x-algolia-application-id · string · header · required

Your Algolia application ID.

x-algolia-api-key · string · header · required

Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference.

Body

application/json

events · (Clicked object IDs after search · object | Added to cart object IDs after search · object | Purchased object IDs after search · object | Converted object IDs after search · object | Clicked object IDs · object | Purchased object IDs · object | Added to cart object IDs · object | Converted object IDs · object | Clicked filters · object | Converted filters · object | Viewed object IDs · object | Viewed filters · object)[] · required

Click and conversion events.

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

Required array length: 1 - 1000 elements

Click event after an Algolia request.

Use this event to track when users click items in the search results. If you're building your category pages with Algolia, you'll also use this event.

Clicked object IDs after search

Show child attributes

events. eventName · string · required

Event name, up to 64 ASCII characters.

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

Required string length: 1 - 64

events. eventType · enum<string> · required

Available options: click

events. index · string · required

Index name (case-sensitive) to which the event's items belong.

Example:

"ALGOLIA_INDEX_NAME"

events. objectIDs · string[] · required

Object IDs of the records that are part of the event.

Required array length: 1 - 20 elements

Example:

["object-1", "object-2", "object-3"]

events. positions · integer[] · required

Position of the clicked item the search results.

You must provide 1 position for each objectID.

Required array length: 1 - 20 elements

Example:

[1, 2, 5]

events. queryID · string · required

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.

Required string length: 32

Example:

"3e48cd0616e466948dd85abf5c3fbbe2"

events. userToken · string · required

Anonymous or pseudonymous user identifier.

Don't use personally identifiable information in user tokens. For more information, see User token.

Required string length: 1 - 129

Example:

"test-user-1"

events. authenticatedUserToken · string

Identifier for authenticated users.

When the user signs in, you can get an identifier from your system and send it as authenticatedUserToken. This lets you keep using the userToken from before the user signed in, while providing a reliable way to identify users across sessions. Don't use personally identifiable information in user tokens. For more information, see User token.

Required string length: 1 - 129

Example:

"c6a52c02-d0c7-4b53-8ce3-2b8fd202f3f9"

events. timestamp · integer<int64>

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

Example:

1687193127

Response

200

application/json

OK

The response of the Insights API.

message · string

Details about the response, such as error messages.

status · integer

The HTTP status code of the response.