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

Client libraries

Use Algolia's API clients, libraries, and integrations to collect events from your UI and send them to the Insights API. See: Algolia's ecosystem

Base URLs

The base URLs for making requests to the Insights API are:

  • https://insights.us.algolia.io (https://insights.algolia.io is an alias)
  • https://insights.de.algolia.io

All requests must use HTTPS.

Authentication

To authenticate your API requests, add these headers:

  • x-algolia-application-id. Your Algolia application ID.
  • x-algolia-api-key. An API key with the necessary permissions to make the request. The required access control list (ACL) to make a request is listed in each endpoint's reference.

You can find your application ID and API key in the Algolia dashboard.

Request format

Request bodies must be JSON objects.

Response status and errors

Response bodies are JSON objects. Deleting a user token returns an empty response body with rate-limiting information as headers.

Successful responses return a 2xx status. Client errors return a 4xx status. Server errors are indicated by a 5xx status. Error responses have a message property with more information.

The Insights API doesn't validate if the event parameters such as indexName, objectIDs, or userToken, correspond to anything in the Search API. It justs checks if they're formatted correctly. Check the Events health section, whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking.

Version

The current version of the Insights API is version 1, as indicated by the /1/ in each endpoint's URL.

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

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.

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) [ 1 .. 1000 ] items

Click and conversion events.

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

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

Event name, up to 64 ASCII characters.

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

eventType
required
string
Value: "click"
index
required
string

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

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

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

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

Position of the clicked item the search results.

You must provide 1 position for each objectID.

queryID
required
string = 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 [ 1 .. 129 ] characters [a-zA-Z0-9_=/+-]{1,129}

Anonymous or pseudonymous user identifier.

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

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

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.

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.

Responses

Request samples 

// Initialize the client
var client = new InsightsClient(
  new InsightsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.PushEventsAsync(
  new InsightsEvents
  {
    Events = new List<EventsItems>
    {
      new EventsItems(
        new ClickedObjectIDsAfterSearch
        {
          EventType = Enum.Parse<ClickEvent>("Click"),
          EventName = "Product Clicked",
          Index = "products",
          UserToken = "user-123456",
          AuthenticatedUserToken = "user-123456",
          Timestamp = 1641290601962L,
          ObjectIDs = new List<string> { "9780545139700", "9780439784542" },
          QueryID = "43b15df305339e827f0ac0bdc5ebcaa7",
          Positions = new List<int> { 7, 6 },
        }
      )
    },
  }
);

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

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

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

User token for which to delete all associated events.

Responses

Request samples 

// Initialize the client
var client = new InsightsClient(
  new InsightsConfig("YOUR_APP_ID", "YOUR_API_KEY", "YOUR_APP_ID_REGION")
);

// Call the API
var response = await client.DeleteUserTokenAsync("test-user-1");

Response samples

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