Archive depth

How far back your plan may reach. The only limit that changes your results rather than refusing your request — so it is the one worth reading carefully.

Plan	Reaches back	`history_days`
Free	30 days	`30`
Build	1 years	`365`
Scale	5 years	`1826`
Archive	The full archive	`null`

Clamped, not refused

Ask for more history than your plan allows and the request still succeeds. Your from is moved forward to the boundary, and the part of the range your plan does cover is answered normally.

Refusing would be defensible, but it breaks every caller who once queried deeper — and it makes the useful part of the answer unreachable because of the part that was not. Clamping keeps the request working.

What clamping must never be is silent, so every response says what happened:

{
  "total": 12,
  "results": [ ... ],
  "history_days": 30,
  "from_clamped": true
}

Field	Means
`history_days`	How far back this plan may reach. `null` means the full archive. Always present on an authenticated response.
`from_clamped`	`true` when a `from` you supplied was moved forward. `false` when nothing of yours was overridden.

The same figure rides on the response as x-plan-history-days, absent when the plan has no limit.

Omitting `from` is not unlimited

A query with no lower bound on a limited plan gets that plan's window, not the whole archive. Nothing of yours was overridden, so from_clamped is false — history_days is what tells you the window is bounded.

# Free tier, no from: answered over the last 30 days.
curl -s -G "https://api.unzoi.com/search" -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "q=inflation"
# -> "history_days": 30, "from_clamped": false

This is also why omitting from is not free even on the top tier: the corpus is sharded by time, and an unbounded range is a request to search every shard that has ever existed. Time windows explains the cost.

Checking before you query

GET /account — and account_status over MCP — report history_days. An agent that reads it once at startup can choose a range that fits instead of discovering the boundary by getting fewer results than it expected.

const { history_days } = await (await fetch(`${API}/account`, { headers })).json();
const earliest = history_days
  ? new Date(Date.now() - history_days * 86_400_000).toISOString().slice(0, 10)
  : "2015-01-01";  // the archive goes back further than most questions do

What it applies to

Every query path: /search, /stories, /top-headlines, and the equivalent MCP tools. It is applied before the query runs, so it cannot be worked around by a filter or a tool argument.