Filter by date without losing half your results

from/to filter by when we indexed a document; published_from/published_to filter by when it was published. Choosing the wrong pair is the most common date bug.

The problem

There are two clocks and they disagree. A page published in 2019 and first indexed last week satisfies a 2019 publication filter and fails a recent-index filter, and vice versa. Reaching for the wrong one produces a result set that looks reasonable and is wrong.

What to send

published_from / published_to

unix timestamp

When the document says it was published. Use this for "what was written about X in 2024".

from / to

unix timestamp

When it entered our index. Use this for "what is new to me since I last polled".

prefer_recent

true

A soft tilt toward newer material, when you want a preference rather than a cutoff.

The code

Pick the clock deliberatelypython

import httpx
from datetime import datetime, timezone

HEADERS = {"x-api-key": "ulb_..."}
ts = lambda y, m, d: int(datetime(y, m, d, tzinfo=timezone.utc).timestamp())

# "What was published about this during 2025?" — publication clock.
written_in_2025 = httpx.get("https://api.unlob.com/search", headers=HEADERS, params={
    "q": "eu ai act compliance",
    "published_from": ts(2025, 1, 1),
    "published_to":   ts(2025, 12, 31),
})

# "What has become available to me since my last run?" — index clock.
# Note this legitimately includes old documents newly indexed.
new_to_me = httpx.get("https://api.unlob.com/search", headers=HEADERS, params={
    "q": "eu ai act compliance",
    "from": last_run_timestamp,
})

The mistake to avoid

Using `from`/`to` when you meant publication dates. It silently excludes older documents that are perfectly on-topic and includes recently-crawled archive material — a result set that looks plausible while answering a different question than the one you asked.

Frequently asked questions

What if a document has no publication date?

Plenty do not — documentation and reference pages frequently carry none. A `published_from` filter cannot include a document whose publication date is unknown, so a strict publication window quietly drops the entire undated tail. If that matters, widen the window or drop to `prefer_recent`.

Which should a monitoring loop use?

`published_from`, advanced to the newest `published_at` you actually received. The index clock will re-show you old material the moment it is crawled, which is rarely what a monitor wants.

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