Keep track of query IDs

Often, conversions start with a and finish outside the search results page, such as on a shopping cart or checkout page. To link conversions to a preceding search, Algolia generates a query ID, a unique identifier for a search query. If you set clickAnalytics to true, the search response includes the queryID. Users often reach the conversion page from several searches, so the page doesn’t know which search produced each item. Each item may need the query ID of a different search. To attribute conversions correctly, capture and send the right query ID with each event.

Get a query ID for every search

If you use InstantSearch or Autocomplete, set the insights option to true:

If you use one of the API clients, set the clickAnalytics parameter to true:

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))
)

Automatic query ID inference for conversion events

If a conversion event and an earlier click event share the same user token, , , and objectID, Algolia automatically infers the queryID. This happens when Algolia processes events. You don’t need to configure anything. This means you might not need to track the query ID manually. For best accuracy, set the queryID whenever possible with one of the following methods.

Match the query ID requirements of your conversion events

Which query IDs you need to keep, and for how long, depends on the events you send when users convert:

convertedObjectIDsAfterSearch accepts one queryID for the whole event. All objectIDs in the event must come from the same search.
addedToCartObjectIDsAfterSearch and purchasedObjectIDsAfterSearch accept a queryID per item in the objectData array. Use this for events with items that originate from different searches, such as a cart checkout. Revenue analytics doesn’t include items without a queryID.

For a conversion event with a single item, or items from one search, one query ID is enough. For a purchase event with items from several searches, keep a query ID for each item.

Track query IDs across pages

Choose one of the following methods to track the query ID from a search until the user converts.

Track query IDs as URL parameters

Add the queryID as a URL parameter to the URL of the destination 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={`/item.html?queryID=${hit.__queryID}`}>
      {/* ... */}
    </a>
  </article>
);

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

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

JavaScript

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

const queryID = searchParams.get('queryID')

URL parameters are the most reliable way to match conversion events to the correct search. For example, users might open several detail pages from a listing page or search results. This pattern is sometimes called page parking. Because each URL carries one queryID, this method works for conversions on the destination page itself. A shared page, such as a checkout page, can hold items from several searches. For conversions there, store a query ID for each item with one of the following methods. When you use URL parameters to track the query ID, follow SEO best practices. For more advice, read the article URL parameter handling in the Search Engine Journal.

Automatically track query IDs

If you use InstantSearch or Autocomplete, you don’t need to track query IDs yourself. Both libraries track the query ID when users click search results. If you pass inferQueryID: true for each call, search-insights automatically includes the queryID in the payload of conversion events.

Track query IDs in cookies or local storage

If you can’t use the automatic query ID tracking in InstantSearch or Autocomplete, build a similar pattern yourself. Track the query ID in a cookie, localStorage, or sessionStorage.

Don’t overwrite a single stored query ID on every search. If users open several detail pages from different searches, a single stored value attaches the wrong query ID to conversion events. This skews attribution.

When a user clicks a result and a query ID is available, write an entry to a cache of query IDs. Key each entry by index name and objectID:

JavaScript

// Store the `queryID` for a specific index and `objectID`
function storeQueryID(index, objectID, queryID) {
  const cache = JSON.parse(localStorage.getItem("objectQueryCache") || "{}");
  cache[`${index}:${objectID}`] = [queryID, Date.now()];
  localStorage.setItem("objectQueryCache", JSON.stringify(prune(cache)));
}

// Retrieve the `queryID` for a specific index and `objectID`
function getQueryID(index, objectID) {
  const cache = JSON.parse(localStorage.getItem("objectQueryCache") || "{}");
  return cache[`${index}:${objectID}`]?.[0];
}

// Keep the newest 5,000 entries, using the stored timestamps
function prune(cache) {
  const entries = Object.entries(cache);
  if (entries.length <= 5000) return cache;
  entries.sort(([, [, a]], [, [, b]]) => b - a);
  return Object.fromEntries(entries.slice(0, 5000));
}

Store a timestamp alongside each queryID so you can cap the size of the cache. When a write exceeds the cap, discard the oldest entries. When a user converts, retrieve the cached queryID for that index and objectID. Include it in the conversion event. After a successful conversion event, delete that entry from the cache. If you store the query ID in a cookie or the browser’s local storage, you may need your users’ consent.

Agentic query IDs

Agentic interfaces can show results that an assistant selected, reordered, or explained. Attribute events from these results to the assistant message that showed them, not only to the 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 of the assistant message in the completion response. Store that assistant message, including its id. When you send the assistant message back as part of the conversation history, reuse the same ID. 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.

The following example uses the search-insights library:

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: 'items',
  eventName: 'Agent Result Clicked',
  objectIDs: ['item-123'],
  positions: [1],
  queryID,
});

Set each position to the item’s visible position in the assistant message, starting at 1. Users can open a detail page from an assistant message and convert later. In that case, pass the agentic queryID like a regular search queryID, such as in the URL:

/item/123?queryID=message_alg_msg_assistant_002

Then include that queryID in the later conversion event.

Track conversions unrelated to a search

To track conversions unrelated to a previous search, send a conversion event without a queryID. For more information about where you can use conversion events without a query ID, see Event types.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Keep track of query IDs

Get a query ID for every search

Automatic query ID inference for conversion events

Match the query ID requirements of your conversion events

Track query IDs across pages

Track query IDs as URL parameters

Automatically track query IDs

Track query IDs in cookies or local storage

Agentic query IDs

Track conversions unrelated to a search

​Get a query ID for every search

​Automatic query ID inference for conversion events

​Match the query ID requirements of your conversion events

​Track query IDs across pages

​Track query IDs as URL parameters

​Automatically track query IDs

​Track query IDs in cookies or local storage

​Agentic query IDs

​Track conversions unrelated to a search

Get a query ID for every search

Automatic query ID inference for conversion events

Match the query ID requirements of your conversion events

Track query IDs across pages

Track query IDs as URL parameters

Automatically track query IDs

Track query IDs in cookies or local storage

Agentic query IDs

Track conversions unrelated to a search