Search Zero Results

Identify failed queries and resolve them through synonym, redirect, or catalog fixes.

Audience: Search operations teams responsible for missed-intent recovery and conversion salvage.

Critical: Resolution workflow is managed at /api/v1/sites/:siteId/search/analytics/zero-results and uses explicit resolution enum values.

Synonyms Redirects Search Analytics

Who This Page Is For

Use this page when customers frequently search for terms that return empty results and you need a repeatable remediation workflow.

Quick Start (2-5 Minutes)

List unresolved zero-result terms

Pull unresolved queries sorted by impact.

GET /api/v1/sites/:siteId/search/analytics/zero-results?resolved=false&sortBy=occurrences&sortOrder=desc

Classify the root cause

Decide whether the issue needs synonym, redirect, or catalog update.

resolution: synonym | redirect | product_added | ignored

Mark query as resolved

Record remediation action for audit and reporting.

POST /api/v1/sites/:siteId/search/analytics/zero-results/:queryId/resolve

Implement fix path

Create synonym/redirect or complete product catalog action.

Use Synonyms or Redirects modules for permanent correction.

Re-check trends

Monitor top queries and zero-result rate over 7-30 days.

GET /api/v1/analytics/search/zero-results?siteId=SITE_ID&days=30

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`queryId`	Required	`uuid/string`	Resolve endpoint	Identifier of zero-result query record.
`resolution`	Required	`synonym \| redirect \| product_added \| ignored`	Resolve endpoint	Explicit resolution classification used for analytics and audit.
`resolved`	Optional	`boolean query`	List endpoint filters	Filter unresolved vs resolved backlog.
`sortBy / sortOrder`	Optional	`query params`	List endpoint sorting	Prioritize by occurrences or recency.

Zero-results endpoints

GET  /api/v1/sites/:siteId/search/analytics/zero-results
POST /api/v1/sites/:siteId/search/analytics/zero-results/:queryId/resolve

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Many users use alternate wording	resolution=synonym	Captures lexical variation with low friction.
Intent should land on curated page	resolution=redirect	Bypasses poor result list and improves journey quality.
Product truly missing from catalog	resolution=product_added	Tracks catalog remediation completion.
Query is noise and should be ignored	resolution=ignored	Closes backlog without unnecessary rules.
Need impact monitoring	Analytics search zero-results endpoint	Measures whether remediation reduced misses.

Common Errors and Fixes

Resolved items keep resurfacing

Cause: Root issue not actually fixed (for example synonym missing or incorrect redirect).

Fix: Validate downstream action after marking resolution.

Resolution endpoint returns permission error

Cause: Role lacks search zero-result resolve permission.

Fix: Grant search resolve permission to responsible operator role.

Backlog too large to manage

Cause: No prioritization by frequency or revenue impact.

Fix: Sort by occurrences and process top impact queries first.

Improvement not visible in analytics

Cause: Short observation window or low traffic term set.

Fix: Track over longer window and compare weekly cohorts.

Production Checklist

Zero-result backlog is reviewed on a fixed cadence.Required
Every resolution has a linked action (synonym, redirect, or catalog update).Required
High-occurrence terms are addressed first.Required
Resolution reason taxonomy is consistently applied.Required
Post-fix impact is validated in search analytics.Required