Freshness: max_age is a contract, not a preference

The contract

max_age on ground is a window — seconds, or 30m, 6h, 7d, 2w — and it is enforced, not weighed. Evidence published inside the window is evidence. Evidence published outside it is never substituted silently: if nothing inside the window exists, status is stale, stale_evidence shows the newest older material so you can see what does exist, and next_actions suggests a wider window.

curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/ground \
  --data-urlencode 'objective=acme zed acquisition' -d max_age=6h

{
  "status": "stale",
  "evidence": [],
  "stale_evidence": [ { "hit": { "…": "…" }, "age_secs": 191000, "reason": "outside max_age (6h)" } ],
  "coverage": { "freshness": { "max_age": 21600, "within_max_age": false, "undated_excluded": true } },
  "next_actions": [ { "action": "widen_max_age", "target": "12h", "why": "nothing inside the freshness window; stale_evidence shows what older material exists" } ]
}

What the window is measured against

Publish date, not crawl date. published_at is what the page declared; a passage that declares no publish date has nothing to measure, and a max_age window excludes it. The receipt says so (freshness.undated_excluded: true, and a line in known_gaps). For a topic where the sources you need are undated — documentation, reference material — leave max_age unset and read age_secs on each item instead, which falls back to crawl time.

prefer_recent on /search is the soft version: a ranking nudge, not a filter. It never produces stale.

The freshness block

"freshness": {
  "max_age": 604800,
  "newest_published_at": 1757790000,
  "oldest_published_at": 1757300000,
  "within_max_age": true,
  "undated_excluded": true
}

newest_published_at and oldest_published_at are over the evidence returned; 0 means no item declared a date. within_max_age is true when every dated item is inside the window and is absent when no window was set.

What the API will not do

There is no on-demand crawl behind ground. If the index holds nothing recent enough, the answer is stale, and /describe reports capabilities.on_demand_crawl: false so an agent can plan for that rather than discover it. The honest options are to widen the window, to accept the stale evidence as stale, or to fetch the page yourself.

Watching a window move

For “what appeared since I last looked”, changes is the call: it reconstructs the evidence as of an earlier instant and diffs it against now, which is the freshness question asked the other way round.

Next

• Grounding — the call max_age belongs to.
• Coverage receipts — where freshness lives.
• Evidence changes — what appeared since.
• Filters and sorting — published_from on a plain search.