---
name: unlob
description: Ground a task in web evidence with provenance and a coverage receipt. Use when you need independently sourced, defensible evidence from the open web and need to know what is missing before you act.
---

# unlob — the evidence layer for agents

unlob compiles the open web into the smallest defensible evidence set for a task, and
tells you when the evidence is not enough. One call returns evidence with provenance
(who originally said it, who republished it, whether sources are independent), a coverage
receipt (what was searched, what was not, how fresh it is), and what to do next.

You do not get a generated answer. You get the evidence and its structure; the reasoning
is yours.

## Setup

- Key: `UNLOB_API_KEY` (starts with `ulb_`). Get one at https://console.unlob.com — the
  free tier needs no card.
- Base URL: `https://api.unlob.com`. Send the key as `x-api-key`.
- Discover the live surface before assuming anything: `GET /describe` (unauthenticated).

## The loop

1. **Ground.** One call per objective.

   ```bash
   curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/ground \
     --data-urlencode 'objective=what changed in the UK AI regulation position this week' \
     -d max_age=7d -d min_independent_origins=2 -d token_budget=3000
   ```

2. **Read `status` first**, then `coverage`.

   | `status` | Meaning | Do |
   |---|---|---|
   | `sufficient` | Enough independent origins, a primary or official source present | Read `evidence` and act |
   | `insufficient` | Evidence exists but does not meet the bar | Follow `next_actions`, or say the evidence is thin |
   | `stale` | Nothing inside `max_age`; `stale_evidence` shows what older evidence exists | Widen `max_age` or report that nothing recent was found |
   | `partial` | Part of the index was unreachable | Retry; never treat the answer as complete |
   | `empty` | Nothing found | Reformulate, or use `why_not` before asserting absence |

3. **Use the provenance.** Each evidence item carries `source_role` (official, primary,
   secondary, aggregator, ugc), `origin_type` (original, wire, press_release, republish),
   its `origin` and `owner`, and an `independence_score`. `coverage.independent_origins`
   counts origins with distinct owners — seventeen URLs of one wire story are one origin.

4. **Check `risk_flags`** on each item before quoting it. `instruction_like` means the
   text addresses an AI system rather than a reader. Pass `strip_instruction_like=true`
   to have those sentences removed server-side.

5. **Fetch full text only when you need it.** `snippet` is the passage. When a
   `next_actions` entry says `get_document`, call `GET /doc/{id}`.

6. **Before asserting that something does not exist**, ask `GET /why_not?url=…`. An
   absent URL and an absent topic are different findings, and the receipt's
   `known_gaps` tells you which parts of the corpus were not searched.

## Watching for change

`GET /changes?objective=…&since=7d&known_urls=<url1>,<url2>` reports what appeared since
then — new evidence, origins gained, an official or primary source appearing, evidence that
newly contradicts a `claim` — and whether each URL you relied on is still `present`,
`removed` (with the reason and its replacement) or `unknown`. `provenance.limitations`
says what it cannot know: removed passages are not reconstructable, so before-counts are
lower bounds.

## Budgets

- `token_budget` caps the evidence returned; `budget.context_tokens` reports what was
  packed. Default 3000.
- `latency_budget_ms` bounds the per-story lookups; when it cuts in,
  `coverage.not_searched.story_expansion_truncated` is true.
- Calls cost credits: `ground` 5 and `changes` 10, however many stories they expand; a
  search or a document 1; a call that runs and fails 1. `GET /describe` lists every cost,
  and each response says what it charged in `x-credits-charged`.

## Over MCP

Connect to `https://api.unlob.com/mcp` with the same header. `?profile=grounding` lists
only `ground` and `get_document`, which is the right surface for most tasks; the default
profile lists every tool, including the graph operations (`corroborate`, `dossier`,
`authorities`, `related`, `path`, `assemble_context`).

## Rules of thumb

- Prefer `ground` for "what should I know about X". Prefer `search` for "find the page
  that says Y".
- Never restate `partial: true` results as complete.
- Quote the `url` of the origin, not of a republish.
- When two evidence items share an `owner`, they are not independent confirmation.