What does 200 mean on GET /changes?

New evidence, origins and roles gained, contradictions gained, what became of known_urls, and both receipts. Read `status` first.

What does 400 mean on GET /changes?

A `since` that does not parse, or is not in the past.

What does 401 mean on GET /changes?

Missing, unknown or revoked key. A key minted moments ago can answer 401 until it propagates to the serving fleet.

What does 429 mean on GET /changes?

Over the per-minute rate (spent in credits), or a hard-capped key without the credits this call costs. `retry-after` is present on the rate-limit case only.

What changed in the evidence since an instant

get /changes

Request

curl \
  -H "x-api-key: $UNLOB_API_KEY" \
  "https://api.unlob.com/changes?objective=<objective>&since=<since>"

Behaviour

Deterministic: the evidence set is built twice, once over everything and once over only what had been crawled by `since`, and the two are diffed. `known_urls` are answered like why_not: present, removed with the reason (and the passage that superseded it), or unknown.

What it cannot know is stated in `provenance.limitations`: passages removed after `since` are not reconstructable, so before-counts are lower bounds, and 'as of' means crawled by then, not published by then.

Costs 10 credits; a call that runs and fails costs 1.

Parameters

Name	Type	Description
`objective`required	string	What you need evidence for. `q` is accepted as an alias.
`since`required	string	An absolute unix timestamp, a bare number of seconds ago, or a duration ago: 1d, 12h, 2w.
`token_budget`	integer	Ceiling on the evidence returned, in estimated tokens. Default 3000.
`known_urls`	string	Comma list of URLs you relied on before; each comes back present, removed (with the reason) or unknown.
`claim`	string	Experimental: also report evidence that newly contradicts this claim.
`mode`	string	keyword \| semantic \| hybrid (default).
`vertical`	string	Restrict to one vertical.
`lang`	string	Single language code.
`safe`	boolean	true (default) drops explicit content.

Responses

Status	Meaning
`200`	New evidence, origins and roles gained, contradictions gained, what became of known_urls, and both receipts. Read `status` first.
`400`	A `since` that does not parse, or is not in the past.
`401`	Missing, unknown or revoked key. A key minted moments ago can answer 401 until it propagates to the serving fleet.
`429`	Over the per-minute rate (spent in credits), or a hard-capped key without the credits this call costs. `retry-after` is present on the rate-limit case only.

Response body

ChangesResponse

Name	Type	Description
`budget`required	object	—
`contradictions_gained`	string[]	—
`coverage`required	object	The coverage receipt
`coverage_before`required	object	The coverage receipt
`independent_origins`required	object	—
`known_urls`	object[]	—
`new_evidence`required	object[]	Evidence items that did not exist as of since
`next_actions`required	object[]	—
`objective`required	string	—
`origins_gained`required	object[]	—
`provenance`required	object	—
`roles_gained`required	string[]	Source roles present now that were missing as of since
`since`required	integer	The instant diffed against, as unix seconds
`status`required	"changed" \| "unchanged" \| "partial"	—

The same call over MCP

This capability is evidence_changes on the MCP server, taking the same parameters and returning the same body. A parity test in the API fails the build if the two ever diverge, so you can read either reference and use the other.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "evidence_changes",
    "arguments": {
      "objective": "<objective>",
      "since": "<since>"
    }
  }
}

Most clients build that frame for you — see Connect a client.

See Errors for what to do with each status, and Retries and backoff for which are worth repeating.

FAQ

What does 200 mean on GET /changes?: New evidence, origins and roles gained, contradictions gained, what became of known_urls, and both receipts. Read `status` first.
What does 400 mean on GET /changes?: A `since` that does not parse, or is not in the past.
What does 401 mean on GET /changes?: Missing, unknown or revoked key. A key minted moments ago can answer 401 until it propagates to the serving fleet.
What does 429 mean on GET /changes?: Over the per-minute rate (spent in credits), or a hard-capped key without the credits this call costs. `retry-after` is present on the rate-limit case only.