Keep track of query IDs

Often, conversions start with a and finish outside the search results page. For example, consider this sequence of user on an ecommerce website:

User searches for a product or browses a category page.
User clicks on one or more products and opens their product detail pages.
After visiting one or more product detail pages, the user adds the product they like the most to the shopping cart.

To track conversion events related to an Algolia search query, capture and send the search queryID with the event. To keep track of queryIDs across pages, include them as URL parameters. To track conversions unrelated to a previous search, you can send a conversion event without a queryID.

Events without a query ID are not considered for most Algolia features. For more information about the types of events accepted by each feature, refer to the Events by features table.

If you’re using the Google Tag Manager connector, see its documentation.

Automatic query ID inference for conversion events

Algolia automatically infers the queryID for a conversion event from an earlier click event if the events share the same user token, , , and objectID. This happens when Algolia processes events: no additional configuration is required. This means manual queryID tracking may not be necessary. However, for best accuracy, set the queryID whenever possible.

Get the `queryID` for every search

To generate a queryID with every search, set the clickAnalytics parameter to true. If you’re using one of the API clients, run:

var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(new SearchParamsObject { ClickAnalytics = true })
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    clickAnalytics: true,
  ),
);

response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
  search.NewEmptySearchParamsObject().SetClickAnalytics(true))))
if err != nil {
  // handle the eventual error
  panic(err)
}

SearchResponse response = client.searchSingleIndex("INDEX_NAME", new SearchParamsObject().setClickAnalytics(true), Hit.class);

const response = await client.searchSingleIndex({ indexName: 'indexName', searchParams: { clickAnalytics: true } });

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(clickAnalytics = true),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['clickAnalytics' => true,
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "clickAnalytics": True,
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(click_analytics: true)
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        clickAnalytics = Some(true)
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(clickAnalytics: true))
)

If you’re using InstantSearch or Autocomplete, set the insights option to true:

Use InstantSearch or Autocomplete to track the `queryID` for conversion events

InstantSearch and Autocomplete keep track of the queryID when users click search results. When sending conversion events, search-insights automatically includes the queryID in the event payload if you pass inferQueryID: true for each call.

Track the `queryID` as a URL parameter

You can add the queryID as a URL parameter to the URL of the product detail page. For example, on your InstantSearch search results page:

search.addWidgets([
  instantsearch.widgets.hits({
    templates: {
      item: (item, { html }) =>
        html`...`
    }
  })
]);

const Hit = ({ hit }) => (
  <article>
    <a href={`/product.html?queryID=${hit.__queryID}`}>
      {/* ... */}
    </a>
  </article>
);

<ais-hits>
  <template v-slot:item="{ item }">
    <a href="/product.html?queryID={{item.__queryID}}">
      ...
    </a>
  </template>
</ais-hits>

To read the queryID from the URL, you can use the URL API:

JavaScript

const url = new URL(window.location.href)
const searchParams = url.searchParams

const queryID = searchParams.get('queryID')

Tracking the queryID with URL parameters is the best way to ensure that conversion events match the correct search. For example, users might open several product detail pages from your category page or search results. This pattern is sometimes called page parking. When you use URL parameters to keep track of the query ID, follow SEO best practices. For more advice, read the article URL parameter handling in the Search Engine Journal.

Track the `queryID` in cookies or local storage

You could track the queryID in a cookie, localStorage, or sessionStorage. For example, to store the latest queryID in the browser’s local storage:

JavaScript

// Write `queryID` to local storage
localStorage.setItem("queryID", queryID);

// Read `queryID` from local storage
let queryID = localStorage.getItem("queryID");

This example only stores one queryID from the last search query that the user performed. If the user has several product detail pages open from previous searches, the conversion event won’t have the correct queryID. Storing the queryID in a cookie or the browser’s local storage may require your users’ consent.

Send the conversion event

To send the conversion event, use the convertedObjectIDsAfterSearch method. If no queryID is provided, Algolia will attempt to infer it based on an earlier click event that shares the same objectID, app, index, and user token. This ensures more accurate tracking of conversions even when explicit queryID tracking is unavailable.

Agentic query IDs

Agentic interfaces can show results that were selected, reordered, or explained by an assistant. In these cases, the event should be attributed to the assistant message that showed the result, not only to an underlying Search API request. If you use InstantSearch Chat, InstantSearch creates and sends this agentic queryID automatically for events from assistant-rendered results. If you integrate with the Agent Studio API yourself, use the assistant message ID from your conversation state. With Agent Studio, this is the id from the assistant message returned by the completion response. Store that assistant message, including its id, and reuse the same ID when you send the assistant message back as part of the conversation history. Build the agentic queryID from that assistant message ID:

message_<assistantMessageId>

For example, if the assistant message ID is alg_msg_assistant_002, the queryID is:

message_alg_msg_assistant_002

Keep this value stable for the lifetime of the assistant message:

Use the same queryID for all results shown in the same assistant message.
Use the same queryID for clicks and conversions that come from those results.
Don’t create a new queryID for each render, click, or event retry.
Don’t use an agentic queryID for events that aren’t caused by an agent-rendered result.

Complete search-insights example:

JavaScript

import aa from 'search-insights';

aa('init', {
  appId: 'ALGOLIA_APPLICATION_ID',
  apiKey: 'ALGOLIA_SEARCH_API_KEY',
});

aa('setUserToken', 'user-123');

// Response body from the Agent Studio completions endpoint.
const assistantMessage = await completionResponse.json();

const queryID = `message_${assistantMessage.id}`;

aa('clickedObjectIDsAfterSearch', {
  index: 'products',
  eventName: 'Agent Result Clicked',
  objectIDs: ['product-123'],
  positions: [1],
  queryID,
  agentId: 'AGENT_ID',
  toolCallId: 'display-results-1',
});

Positions should match the item’s visible position in the assistant message, starting at 1. If a user opens a product detail page from an assistant message and converts later, pass the agentic queryID through the same way you would pass a regular search queryID, such as in the URL:

/product/123?queryID=message_alg_msg_assistant_002

Then include that queryID in the later conversion event.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Keep track of query IDs

Automatic query ID inference for conversion events

Get the `queryID` for every search

Use InstantSearch or Autocomplete to track the `queryID` for conversion events

Track the `queryID` as a URL parameter

Track the `queryID` in cookies or local storage

Send the conversion event

Agentic query IDs

​Automatic query ID inference for conversion events

​Get the queryID for every search

​Use InstantSearch or Autocomplete to track the queryID for conversion events

​Track the queryID as a URL parameter

​Track the queryID in cookies or local storage

​Send the conversion event

​Agentic query IDs

Automatic query ID inference for conversion events

Get the `queryID` for every search

Use InstantSearch or Autocomplete to track the `queryID` for conversion events

Track the `queryID` as a URL parameter

Track the `queryID` in cookies or local storage

Send the conversion event

Agentic query IDs