Analytics rules and metrics

Two independent systems share the analytics tag. Metrics are computed on demand from the same events your storefront already sends to POST /events (see Events and recommendations) — nothing to configure beyond sending events with found, doc_ids and value. Analytics rules are a separate, named counter engine you configure explicitly, for things a metrics query doesn't cover — a "popular searches" widget backed by your own collection, or a raw event log for one property.

Every operation on this page needs a full key (see keys and scopes). None of them run a model, so none are billed in AI credits.

Query-performance metrics

Four read-only endpoints aggregate stored search events over a date range. Every one requires a bounded from/to (ISO 8601, at most 366 days) and accepts an optional collection filter:

const queries = await client.analytics.listAnalyticsQueryMetrics({
  from: "2026-08-01",
  to: "2026-08-31",
  collection: "products",
  limit: 50,
});
// queries.data[0] -> { q, searches, results_found_rate, clicks, ctr, no_click_rate, add_to_carts, purchases, revenue, conversion_rate, revenue_per_search }

curl -G https://api.aacsearch.com/v1/analytics/metrics/zero-results \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" \
  --data-urlencode "from=2026-08-01" --data-urlencode "to=2026-08-31"

The queries / zero-results / revenue-attribution responses page with limit/offset and carry next_offset (null once you've read every row) and total, the count before pagination. events reports how many raw events the request walked to build the page; truncated: true means the range held more events than one request scans, so the numbers cover only the earliest rows — narrow the range rather than trust a truncated total. The zero-result share is search-weighted (1 - results_found_rate), not query-weighted, so a handful of popular zero-hit queries move it more than many rare ones.

There is no dedicated widget for these — they back the console's insights screens; call them directly for your own dashboard.

Analytics rules

An analytics rule names a counter or log fed by createAnalyticsEvent, independent of the events pipeline above:

A rule has a type, the collection and event_type it watches, and a params object whose shape depends on type:

await client.analytics.createAnalyticsRule({
  name: "products-popular-queries",
  type: "popular_queries",
  collection: "products",
  event_type: "search",
  params: { destination_collection: "products_popular_queries", limit: 1000 },
});

Send and read rule-scoped events

createAnalyticsEvent — POST /analytics/events — records one event against a named rule:

await client.analytics.createAnalyticsEvent({
  name: "products-popular-queries",
  event_type: "search",
  data: { user_id: "u_42", q: "cordless drill", filter_by: "in_stock:true" },
});

getAnalyticsEvents — GET /analytics/events — reads the most recent events for one user_id and rule name (up to n, max 1000):

const recent = await client.analytics.getAnalyticsEvents({ user_id: "u_42", name: "products-popular-queries", n: 20 });

Deleting a rule (deleteAnalyticsRule) stops new events from being aggregated; it does not delete a rule's destination_collection or the documents already written to it.