ground · unlob Docs

Behaviour

Runs retrieval, story deduplication, origin clustering and ranking on the server and returns evidence items rather than links: each says who originally published it (origin_type), who republished it, what kind of source it is (source_role), who owns it, and whether it is independent of the others. `coverage` says what was searched, what was not, how fresh the set is and which source classes are missing; `independent_origins` counts origins with distinct owners, so seventeen copies of one wire story are one origin.

Read `status` first. sufficient: enough independent origins and a primary or official source. insufficient: evidence exists but does not meet the bar — `next_actions` says what would. stale: nothing inside max_age; `stale_evidence` shows what older material exists. partial: part of the index was unreachable — never treat the answer as complete. empty: nothing found.

No generated answer is returned: the evidence and its structure are, and the reasoning is yours.

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

Arguments

inputSchema

Name	Type	Description
`claim`	string	Experimental: relate each evidence item to this claim as supports / contradicts / qualifies / unresolved. Heuristic; no model.
`lang`	string	Single language code
`latency_budget_ms`	integer	Bound on the time spent expanding stories into their members; when it cuts in, coverage.not_searched.story_expansion_truncated is true
`max_age`	string	Freshness contract: seconds, or 30m / 6h / 7d / 2w. Evidence published outside the window is never substituted silently; it is reported as stale_evidence when nothing inside the window exists
`min_independent_origins`	integer	Origins with distinct owners required for status=sufficient
`mode`	"keyword" \| "semantic" \| "hybrid"	—
`objective`required	string	What you need evidence for — a question, a task, or a claim to check
`require_role`	array \| string	Roles of which at least one must be present for sufficient. Default primary,official. Empty means no requirement.
`safe`	boolean	true (the default) drops explicit content
`strip_instruction_like`	boolean	Remove instruction-like sentences from snippets instead of only flagging them
`token_budget`	integer	Ceiling on the evidence returned, in estimated tokens
`vertical`	string	Restrict to one vertical; the receipt then lists the others as not searched

Argument shapes

1 arguments take either a JSON array or a comma-separated string: require_role. That is the one place the two transports differ in shape. A URL query string cannot carry an array, so the REST form of these is always the comma-separated one; an argument object can carry either.

Returns

A JSON payload in the text content block, and the same payload as structuredContent for clients that support it.

outputSchema

Name	Type	Description
`budget`required	object	—
`contradictions`	string[]	Ids of evidence items whose claim_relation is contradicts
`coverage`required	object	The coverage receipt
`evidence`required	object[]	—
`next_actions`required	object[]	—
`objective`required	string	—
`origins`required	object[]	—
`provenance`required	object	—
`stale_evidence`	object[]	Only when max_age was set and nothing inside it was found
`status`required	"sufficient" \| "insufficient" \| "stale" \| "partial" \| "empty"	—

Calling it

Over Streamable HTTP, with the required arguments filled in:

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

Most clients do this for you — see Connect a client. To drive it by hand, complete the startup lifecycle first.

The same call over REST

If your client does not speak MCP, this capability is GET /ground, taking the same parameters and returning the same body.

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