unlob Docs
Console
Browse documentation

Which call answers which question

Every endpoint and tool reduces to one decision — what kind of question is this, and does it need evidence or a page.

Every call this API offers answers one of five underlying question shapes, not twelve unrelated ones. Knowing which shape you are looking at settles which endpoint to call faster than reading each reference page in turn.

The five shapes

Your question sounds likeShapeCall
“Find pages about X”Lookupsearch
“What should I know about X”Synthesisassemble_context
“Is this actually true / widely reported”Verificationcorroborate
“What connects to this”Traversalrelated, path, authorities, dossier
“Why don’t I see X”Coveragewhy_not

similar, browse, get_document and account sit outside the five because each answers a narrower, mechanical question — “more like this one”, “what’s newest”, “give me the whole page”, “what does my key have left” — rather than a shape of research question. They are no less useful; they are just not decisions in the way the five above are.

Lookup versus synthesis: the one that actually matters

Most of the calls above are specialised. This one choice is not, and it is the one worth internalising: search returns a ranked list of passages for you to read and combine yourself; assemble_context runs that whole loop — search, deduplicate near-duplicates, corroborate, rank, pack to a token budget — on the server and hands you a reading set with each item already carrying the reason it was included.

Reach for search when the question is “find me the page that says Y” — you know roughly what you are looking for and want to read it yourself. Reach for assemble_context when the question is “what should I know about X” — you want an answer built from several sources, not a list to build it from. Defaulting to assemble_context for anything open-ended is usually right; it costs 3 credits, what a search and one corroborate would, so there is no efficiency argument for doing the loop yourself unless you need to intervene partway through — filtering results before corroborating them, say, rather than after.

The graph calls, and when a second search is the wrong move

related, path, authorities and dossier all read the same underlying graph — passages linked to hosts, near-duplicate stories, topics and entities — from four different entry points. The tell that you want one of these instead of another search is that your next step was going to be searching again, using something the first result told you:

  • You have one passage and want what is connected to it → related, a bounded walk outward.
  • You have two passages and want to know if — and how — they connect → path, the shortest chain between them.
  • You have a topic or entity and do not yet know the vocabulary → authorities, ranked by centrality rather than by match to a query, so you read the central sources first instead of stumbling into them by luck.
  • You have a named entity and want everything about it in one shot → dossier, which also returns co-mentioned entities — the leads you did not know to search for.

Each of these replaces what would otherwise be several searches and a manual merge. See The Coverage Graph for the underlying model and Graph recipes for these chained into a full research loop.

Verification is a separate step, not a search option

corroborate is not a way of searching more carefully — it is a check you run on a result you already have, and it answers a question search cannot: how many independent hosts assert this, as opposed to how many results mention it. Forty rows in a result list and one independently reported fact look identical to a plain search; corroborate is what tells them apart. Run it on anything you intend to state as established before you state it, not on everything you read.

A worked example

The question: “What is independently corroborated about a hypothetical acquisition, and what does not connect anywhere else?”

  1. search with the company name and min_independent_sources=2 — a first pass, corroborated by default rather than as an afterthought.
  2. corroborate on the two or three results that look load-bearing, to get an exact count and the host list behind each.
  3. dossier on the acquiring company — the co-mentioned entities are the leads: the target, the regulators, the executives named alongside it.
  4. path between the acquiring company and one lead that looks connected but is not obviously so, to confirm the link is real rather than a coincidence of wording.
  5. assemble_context on the refined question, once steps 1 through 4 have narrowed what “the refined question” actually is, for a packed reading set to write from.

Five kinds of call, 10 credits with a single corroborate and 2 more for each extra one, and a research loop that would otherwise be a dozen searches and a lot of manual cross-referencing compressed into one pass.

What this does not decide for you

None of the calls above tell you whether a source is worth trusting beyond its corroboration count and host authority — host_rank and quality are signals, not a verdict, and corroborate counts independent reporting, not correctness. Ten independent outlets can all repeat the same wrong wire report if none of them did original reporting; corroborate will still return a high count, because from the index’s point of view they are ten distinct hosts. Corroboration is evidence, not proof, and it is worth reading the actual sources list rather than only the count when a claim matters.

FAQ

Do I need to call search before assemble_context? No — assemble_context runs its own retrieval internally. Call search first only when you want to inspect or filter the candidates yourself before the corroboration and packing step runs.

Is corroborate worth calling on every result? No. It is a targeted check for claims you intend to rely on, not a blanket pass over everything a search returns — most results in a list do not need independent verification to be useful context.

Which call is cheapest? A search, a document, similar, browse and why_not cost 1 credit; the graph calls cost 2; assemble_context 3; ground 5; changes 10. What a call returns never changes its price, so assemble_context costs 3 credits however much it packs. See Pricing.

Bottom line

Start from the shape of the question, not the list of endpoints: lookup reaches for search, synthesis for assemble_context, verification for corroborate, and traversal for whichever of the four graph calls matches what you already have in hand. Everything else on this site’s API reference and MCP tools pages is the detail of how each one works once you know which one you want.

Next