Send events

Send a list of events in a single request.

This page documents an earlier version of the API client. For the latest version, see Send events.

Required ACL: search

Sending multiple events in a batch can be useful when:

• Importing historical data
• Sending events from your backend

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

When you’re sending historical events, make sure to set correct timestamps for all events, or else every event will have the same timestamp.

For sending real-time events, use the dedicated methods instead:

• clickedObjectIDsAfterSearch
• convertedObjectIDsAfterSearch
• addedToCartObjectIDsAfterSearch
• purchasedObjectIDsAfterSearch
• clickedObjectIDs
• convertedObjectIDs
• addedToCartObjectIDs
• purchasedObjectIDs
• clickedFilters
• convertedFilters
• viewedObjectIDs
• viewedFilters

For more information, see Get started with events.

Examples

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

For more information about initializing the JavaScript Insights client aa, see Initialize the Insights client.

C#

var insights = new InsightsClient(
  "YourApplicationID",
  "YourSearchOnlyAPIKey"
);

var events = new List<InsightsEvent>(){
  // `clickedObjectIDsAfterSearch`
  new InsightsEvent(
    EventType = "click",
    UserToken = "user-123456",
    EventName = "Example Clicked",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    Positions = new List<uint> { 17, 19 },
    QueryID = "queryID",
    Timestamp = <%= DateTime.now.strftime('%Q') %>;
  ),
  // `viewedObjectIDs`
  new InsightsEvent(
    EventType = "view",
    UserToken = "user-123456",
    EventName = "Example Viewed",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    Timestamp = <%= DateTime.now.strftime('%Q') %>;
  ),
  // `convertedObjectIDsAfterSearch`
  new InsightsEvent(
    EventType = "conversion",
    UserToken = "user-123456",
    EventName = "Example Converted",
    Index = "YourIndexName",
    ObjectIDs = new List<string>{ "objectID-1", "objectID-2" },
    QueryID = "queryID",
  )
};

insights.sendEventsAsync(events);

Parameters

events · object[] · required

An array of event objects

Show child attributes

eventName · string · 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 Twilio Segment’s object-action framework.

eventType · enum<string> · required

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

See also: Event types

index · string · required

Name of the Algolia index.

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

userToken · string · required

Anonymous user identifier.

See also: User token

authenticatedUserToken · string

Pseudonymous identifier for authenticated users.

Don’t include personally identifiable information in user tokens.

See also: User token

currency · string

PHP, Ruby, JavaScript, Python only: 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.

eventSubtype · addToCart | purchase

PHP, Ruby, JavaScript, Python, Go only: Subtype of a conversion event (eventType: conversion). Either addToCart or purchase. For other event types, this should be omitted.

This lets Algolia provide more detailed analytics reports.

filters · string[]

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.

objectData · object[]

PHP, Ruby, JavaScript, Python, Kotlin only: Extra information about the records involved in the event, for example, price and quantities of purchased products.

If provided, must be the same length as objectIDs.

If you include pricing information, you must also specify the currency parameter.

objectIDs · string[]

List of object IDs for items of an Algolia index.

You can include up to 20 object IDs.

A single event must not include both objectIDs and filters.

positions · string[]

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.

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.

timestamp · integer

Time of the event in milliseconds since the Unix epoch. 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.

• Timestamps may be up to 4 days in the past.
• For events with query ID: timestamps must be within 1 hour of the corresponding search or browse requests.

value · number | string

PHP, Ruby, JavaScript, Python only: The monetary value of the event, measured in currency. For example, the total value of a purchase.

If you assign a value, you must also specify the currency parameter.

Must be a decimal number with no more than 16 characters (including non-digit characters).

additionalParams · object

JavaScript only: Additional parameters for the search-insights library.

Example:

JavaScript

aa(
  "sendEvents",
  [
    // …
  ],
  {
    headers: {
      "X-Algolia-Application-Id": "YourApplicationID",
      "X-Algolia-API-Key": "YourSearchOnlyAPIKey",
    },
    inferQueryID: true,
  },
);

Show child attributes

headers · object

Additional headers you want to add to the request as key-value pairs. For example, you can add your credentials as headers, which lets multiple clients use different credentials for every request.

inferQueryID · boolean

Whether to infer the query ID for conversion events from previous click events.

discount · number | string

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

Must be a decimal number with no more than 16 characters (including non-digit characters).

price · number | string

The price of the item. This should be the final price, including any discounts.

Must be a decimal number with no more than 16 characters (including non-digit characters).

quantity · number

The quantity of the purchased or added-to-cart item. The total value of a purchase is the sum of quantity multiplied by the price of each purchased item.

queryID · string

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

Objects without a query ID aren’t included in revenue analytics. For more information, see Revenue transactions.

See also: Keep track of query IDs