Why is this a job rather than a synchronous call?

Because it opens a real browser session per source. Five platform-aware scrapes do not fit inside a sane request timeout, so the call returns a job id and you poll get_job — or hand it a callbackUrl and let it come to you.

What happens when one source cannot be scraped?

That result comes back with its own status and a note saying why, and the rest of the job completes normally. You are billed for pages actually scraped, so a source that refused you does not appear on the invoice.

Observation & data

Search, then actually read the results

An asynchronous research pass: run the search, then scrape the top results with platform-aware handling for sites a plain fetch cannot read, and return a job id.

Get an API key MCP setup

deep_search

What it is

The job: Do the research pass an agent would otherwise fake from search snippets.

A snippet is not a source. deep_search runs the ranked search and then scrapes the top N results for cleaned content, with platform-aware handling for the sites that a naive fetch reads badly or not at all — Reddit and X among them. The result is content an agent can actually reason over rather than a list of titles.

It is asynchronous because it is slow by nature: you get a job id immediately and poll get_job for { query, results, scraped }, where each result carries its own status and a note explaining anything that did not work. A page that could not be scraped says so rather than silently returning empty.

It accepts the full anti-ban surface — proxy, rotation, session key, account and session persistence — because reading a discussion site at volume is exactly the workload that gets an anonymous datacenter IP turned away.

The call

Call it exactly like this.

Copied from the tool's registration and the route handler — not paraphrased.

MCPdeep_search.mcp.jsonjson

// MCP tool call — server "twin-browser"
{
  "tool": "deep_search",
  "arguments": {
    "query": "self-hosted vector database cost comparison",
    "count": 10,
    "topN": 5
  }
}

POST /api/v1/search (depth: "deep")request.shbash

curl -X POST https://twin-browser.com/api/v1/search \
  -H "Authorization: Bearer $TWIN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"self-hosted vector database cost comparison","depth":"deep","count":10,"topN":5}'

Parameters accepted by deep_search
Parameter	Type	What it does
query*	string	The search query.
count	number	Number of ranked results to consider, 1–20. Default 10.
topN	number	How many top results to scrape for content, 1–10. Default 3.
proxy	string	Your own egress proxy URL.
proxyRotate	boolean	Force per-request proxy rotation.
sessionKey	string	Explicit account stickiness key.
account	string	Account/credential label, for scraping a source you are signed into.
persistSession	boolean	Persist and resume browser session state for this account.
callbackUrl	string	Absolute http(s) URL to POST the result to on completion.
callbackSecret	string	Secret used to HMAC-sign the callback body.

Returns

response.jsonjson

HTTP 202
{ "jobId": "…" }

// then GET /api/v1/jobs/{id} →
{ "status": "complete",
  "result": {
    "query": "…",
    "scraped": 5,
    "results": [ { "title": "…", "url": "…", "snippet": "…",
                   "content": "…", "status": "ok", "note": null } ]
  } }

What it costs

3 credits + 5 per page scraped

3 credits for the search plus 5 for each page actually scraped — 5× the cost of a shallow fetch in search, because a platform-aware scrape is a real browser session per source. The reservation is sized to your topN and settled down to the pages that actually came back.

See the full rate card

Which one

When a different tool is the right call.

The honest answer is often the neighbouring tool. These are the trades.

search

search is synchronous, cheaper per page, and enough when the sources are ordinary web pages. deep_search earns its price only on sources a plain fetch reads badly. Do not pay for it by default.

submit_crawl

A crawl walks one site exhaustively; deep_search reads the best few pages across many sites. Research versus inventory.

submit_crawl

Questions

deep_search, answered.

Why is this a job rather than a synchronous call?: Because it opens a real browser session per source. Five platform-aware scrapes do not fit inside a sane request timeout, so the call returns a job id and you poll get_job — or hand it a callbackUrl and let it come to you.
What happens when one source cannot be scraped?: That result comes back with its own status and a note saying why, and the rest of the job completes normally. You are billed for pages actually scraped, so a source that refused you does not appear on the invoice.

Keep going

The rest of the tool set.

search

Find pages, and optionally have them read for you, in one call.

get_job

Find out whether the thing you started has finished, and get what it produced.

extract

Get data off a page in the shape your code already expects.

etl

Turn web content into something you can ask questions of, without building a pipeline.

The mechanism behind it:Proxy & egress

Get an API key All tools