# Find docs searches with zero results

> Capture failed docs searches and connect them to activation, support load, and API adoption so docs work targets real blockers.

## Agent adaptation contract

- Canonical human page: https://agentry.sh/workflows/docs-search-zero-results
- Execution mode: on_demand
- Immutable automation template: none
- Applies to: devtools-api, b2b-saas, open-source, content-media
- Required example events: docs_search
- Required Agentry resources: none declared
- Do not use when:
  - Do not use until the example events are mapped to observed project signals, the current onboarding state is verified, and live event/property reads prove the required data is present.
- Ask before using:
  - Which observed events map to docs_search? Is the current onboarding state verified, and do live event/property reads show non-synthetic traffic for them?
  - Which live properties provide docs_search.query, docs_search.result_count, docs_search.path, and which stable user or account identifier joins the signals?

This is an adaptable workflow example, not an API recipe. Map event and property names to the project's saved signal map, require status: "verified" from GET /v1/projects/:project_id/onboarding, and confirm the required signals through live event/property metadata and rows. Fetch current OpenAPI or query-blueprint details before making calls. Do not infer unattended authority from this page.

## Why this matters

Docs search queries are user intent in plain text. Zero-result searches tell you what users expected to find and could not.

## What you get

- Top zero-result queries
- Pages where searches happen
- Users or accounts affected
- Follow-up impact: activation failure, support tickets, or API inactivity

## Walk through it

**You:**
> What are people searching for in docs and not finding?

**Agent:**
> I'll rank docs searches with result_count = 0.

```text
Endpoint: POST /v1/projects/:project_id/analytics/query
Exact shape: /v1/openapi.json?path=%2Fv1%2Fprojects%2F%7Bproject_id%7D%2Fanalytics%2Fquery&method=post
Custom HogQL goes in the OpenAPI-defined `query` field.
Concept fields:
  query: "SELECT properties.query AS query, properties.path AS path, count() AS searches, count(DISTINCT distinct_id) AS users FROM events WHERE event = 'docs_search' AND toInt(properties.result_count) = 0 AND timestamp > now() - INTERVAL 30 DAY GROUP BY query, path ORDER BY searches DESC LIMIT 50"
```

## The output

The agent returns search gaps and suggested docs pages to create or improve.

## Setting it up

Emit `docs_search` from your docs site search component. Include result count and current path.

## Variations

- *"Only show searches from logged-in accounts."*
- *"Find zero-result searches before API inactivity."*
- *"Draft the missing docs outline for the top query."*