Debug a search that returns nothing

Remove filters one at a time from the most restrictive downward, then use why_not to distinguish a filter problem from a coverage gap.

The problem

An empty result set has two very different causes — you over-filtered, or the content is not in the index — and they need opposite fixes. Guessing wastes an afternoon; the API will tell you which it is.

What to send

limit

Returns the count only. The cheapest way to bisect filters without paying for payloads.

why_not

a specific URL

Answers present / removed-with-reason / never-admitted for a page you expected.

The code

Bisect the filterspython

import httpx

HEADERS = {"x-api-key": "ulb_..."}
API = "https://api.unlob.com/search"

full = {
    "q": "kubernetes ingress timeout",
    "vertical": "code",
    "min_quality": 80,
    "min_independent_sources": 3,
    "published_from": 1767225600,
    "content_type[]": "docs",
}

# Drop one filter at a time and count. limit=0 returns the count only,
# so this whole loop costs almost nothing in tokens.
for dropped in [None, *full.keys() - {"q"}]:
    params = {k: v for k, v in full.items() if k != dropped}
    n = httpx.get(API, headers=HEADERS, params={**params, "limit": 0}).json()["total"]
    print(f"{n:>5}  without {dropped or 'nothing'}")

Then ask about a page you expectedbash

curl -H "x-api-key: ulb_..." \
  "https://api.unlob.com/why_not?url=https://kubernetes.io/docs/concepts/services-networking/ingress/"

# -> {"status":"present"}                      your filters excluded it
# -> {"status":"removed","reason":"..."}       it was there and went
# -> {"status":"never-admitted","reason":"..."}  a genuine coverage gap

The mistake to avoid

Assuming an empty result means missing coverage and giving up. The far more common cause is a stacked filter — most often a `published_from` window that excludes every undated document. Check with `limit=0` before you conclude anything about the index.

Frequently asked questions

Which filter is most often the culprit?

A publication-date window, because it silently drops every document with no publication date at all — which is most reference documentation. After that, `min_independent_sources` set above three on a recent topic.

What if why_not says never-admitted?

Then it is a real coverage gap and no combination of parameters will find it. That is worth knowing in one call rather than after an hour of tuning, and it is the answer no other search API will give you.

Try it against your own queries

10,000 requests a month on the free tier, no card. Enough to run a real evaluation set rather than a demo.

Get an API key All recipes