canonical: https://jentic.com/apis/algolia.com/algolia-insights-api

# Algolia Insights API

Jentic publishes the only available OpenAPI specification for the Algolia Insights API, keeping it validated and agent-ready. The Insights API captures user interaction events - clicks, conversions, views, and add-to-carts - that feed Algolia's Recommend, Personalization, Dynamic Re-Ranking, and analytics features. It exposes event ingestion, user-token deletion for GDPR compliance, and a small set of utility endpoints. Send events from your search UI to unlock relevance tuning that learns from real user behavior.

## For AI agents

Send click, conversion, and view events to Algolia so Recommend, Personalization, and Dynamic Re-Ranking can learn from user behavior. Also handles user-token deletion for GDPR.

## Scope

Does not handle search execution, indexing, or recommendation generation - use the Algolia Search and Recommend APIs for those. Use this API for behavioral event capture only.

## Capabilities

- Send click, conversion, and view events tied to a user token via POST /1/events
- Batch up to 1000 events per request to feed Algolia's behavioral relevance models
- Delete all events for a specific user token to comply with GDPR right-to-erasure requests via DELETE /1/usertokens/{userToken}
- Tag events with index name, query ID, and object IDs so they can be tied back to specific search results
- Capture add-to-cart and purchase events with monetary value for revenue attribution

## Use cases

### Click and conversion tracking for search relevance

Send clickedObjectIDsAfterSearch and convertedObjectIDsAfterSearch events from your storefront UI to Algolia. Each event carries the queryID returned by the original search, so Algolia can attribute clicks and conversions to specific queries and feed Dynamic Re-Ranking. Without these events, click and conversion analytics in the Algolia dashboard remain empty.

Example prompt: POST a clickedObjectIDsAfterSearch event to /1/events with userToken 'user_42', queryID from the search, indexName 'products', objectIDs ['sku_123'] and positions [1]

### GDPR data erasure for user tokens

When a user invokes their right to be forgotten, call DELETE /1/usertokens/{userToken} to remove all events associated with that token from Algolia's analytics and recommendation models. The endpoint returns rate-limit headers so you can pace bulk deletions during compliance sweeps.

Example prompt: Call DELETE /1/usertokens/user_42 to wipe all event history for that user token

### Revenue and add-to-cart attribution

Send addedToCartObjectIDsAfterSearch and purchasedObjectIDsAfterSearch events with value, currency, and quantity fields. Algolia ties each event to the originating queryID and attributes revenue to specific searches, giving merchandisers a clear view of which queries drive sales.

Example prompt: POST a purchasedObjectIDsAfterSearch event with objectIDs ['sku_a','sku_b'], objectData containing price 49.99 USD per item, and the queryID from the originating search

### Agent-driven event capture in conversational UIs

An AI agent recommending products through a chat surface can fire view, click, and conversion events as the user interacts with the suggestions. Through Jentic, the agent finds the pushEvents operation by intent, loads the schema, and executes - no manual integration with the Insights endpoint needed.

Example prompt: Search Jentic for 'send Algolia conversion event', load pushEvents, and execute with the user's queryID and the sku they selected

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /1/events | Send a batch of analytics events |
| DELETE | /1/usertokens/{userToken} | Delete all events for a user token |
| GET | /setClientApiKey | Retrieve a temporary client API key |

## Key resources

- **Events** — Click, conversion, view, add-to-cart, and purchase events
- **User Tokens** — Identifiers tying events to a user; deletable for GDPR

## Why Jentic

- **Setup:** Wiring the Algolia Insights API by hand means sending its API key, resolving the insights.{region}.algolia.io host, and batching behavioral events yourself. Through Jentic you install once, import the Insights API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** The Insights API captures events posted to /1/events with the target carried in the request body, so limit the agent to the operations it needs, such as sending events. You choose the operations it may call, so deleting a user token is not included unless you add it.
- **Credential handling:** Your Algolia API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'record a click event' or 'send a conversion event', and Jentic returns the matching Algolia Insights operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Mixpanel API** — General-purpose product analytics with funnels and cohorts
- **Amplitude API** — Behavioral analytics platform with retention and journey analysis
- **Algolia Search API** — Insights events reference queryIDs returned by the Search API
- **Algolia Recommend API** — Recommend models are trained on Insights events

## FAQ

### Why is there no official OpenAPI spec for the Insights API?

Algolia does not publish a standalone OpenAPI specification for the Insights API. Jentic generates and maintains this spec so that AI agents and developers can call the Insights API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Algolia Insights API use?

Two API key headers: x-algolia-application-id and x-algolia-api-key with the search ACL. Through Jentic, both are stored in the vault and injected at request time, so agents never see the raw key.

### Can I track purchases with the Insights API?

Yes. Send a purchasedObjectIDsAfterSearch event to /1/events with objectIDs, objectData (price and quantity), currency, and the originating queryID. Algolia ties the revenue back to the search that produced the click.

### What are the rate limits for the Algolia Insights API?

The spec does not declare numeric rate limits, but each /1/events request can carry up to 1000 events as a single batch. Use batching to stay under throughput limits and watch for 429 responses with Retry-After headers.

### How do I delete user data through Jentic?

Search Jentic for 'delete Algolia user token', load deleteUserToken, and execute with the userToken string. Jentic injects credentials and calls DELETE /1/usertokens/{userToken} - the response includes remaining rate-limit headers.

### Does the Insights API validate the events I send?

It only checks that events are formatted correctly. It does not verify that indexName, objectIDs, or userToken correspond to real records in the Search API. Check the Events health page in the Algolia dashboard to confirm events are usable for Recommend and Dynamic Re-Ranking.

### Can I limit what my agent is allowed to do with the Algolia Insights API?

Yes. Because you run Jentic One yourself, your own rules decide which Insights API operations and credentials the agent can use. You can grant it only the operations it needs, such as sending click, conversion, and view events to /1/events, while withholding others. Destructive operations like deleting a user token via DELETE /1/usertokens/{userToken} stay off unless you explicitly add them.