Twin Browser
Get an API key
PlatformOverviewHow it worksAll toolsREST APIMCP serverIntegrationsDocs
CapabilitiesSemantic dispatch cacheDeterministic replayCross-tenant skill corpusToken-efficient DOMHuman-in-the-loopLive view & videoCredential vaultOverviewSolutions
SolutionsAll use casesAI agentsRPA replacementQA & test automationData extraction
ResourcesGuidesGlossaryBlogCompareFAQStatus
Pricing
Log in

CAPABILITY · SEARCH

Ranked results, blended sources, and an optional deep read

One search call blends web, discussion, news and FAQ clusters with Hacker News, deduped and source-tagged — then optionally fetches and cleans the top results, or scrapes them as a background job.

Start freeAPI reference
POST /api/v1/search

Capability

Inside web search & deep search

Agents that need to find something before they can act on it should not have to bolt on a second vendor. Search returns ranked results from blended sources — web, discussions, news and FAQ clusters, plus Hacker News — deduped by URL with each result tagged by where it came from. Two depths: shallow returns the ranking synchronously and can fetch the top few, and deep hands the scraping to a background job.

Blended and source-tagged

Results merge several clusters and Hacker News, deduped by URL, and every result carries a `source` field — web, discussions, news, faq or hackernews — so you can weight them yourself.

Ranking, or ranking plus content

A plain shallow call returns links. Set `fetchContent` and the top `topN` results are also loaded and cleaned, billed per page fetched.

Deep search as a job

depth: "deep" returns 202 with a jobId and scrapes the top matches platform-aware in the background — the right shape when the read is longer than your request timeout.

Same key, same billing, same audit

Search is a first-class endpoint on the same Bearer key as everything else, with the same credit reserve, refund and audit path.

How it works

The mechanism, in execution order

4 stages, in the order the runtime performs them — not a summary of them.

  1. 1QueryPOST /api/v1/search with a `query` and a `count` (1–20, default 10).
  2. 2Rank and dedupeResults from the blended clusters are merged, deduped by URL and tagged with their source.
  3. 3Optionally readShallow with `fetchContent` loads and cleans the top `topN` results inline; deep submits a job that scrapes them.
  4. 4CollectShallow returns the results directly. Deep returns 202 { jobId } — poll GET /api/v1/jobs/{id}.

In practice

A call you can paste and run

A shallow search with content: 3 credits for the ranking, 1 credit for each of the three pages it also read.

search.shbash
curl -X POST https://twin-browser.com/api/v1/search \
  -H "Authorization: Bearer $TWIN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"headless browser bot detection 2026",
      "count":10,"fetchContent":true,"topN":3}'

# {
#   "results": [
#     { "title": "…", "url": "https://…", "source": "discussions", "content": "…" },
#     …
#   ],
#   "credits_charged": 6
# }
# = 3 for the search + 1 per fetched page × 3
api.twin-browser.com
  1. Querydone
  2. Rank and deduperunning
  3. Optionally readqueued
  4. Collectqueued

What it costs, how to switch it on

Priced from the same rate card the API serves

Every credit figure on this page is read from the rate card behind GET /api/v1/pricing — it is not typed into the copy, so it cannot drift from what you are billed.

3 credits shallow · +1 per fetched page

A shallow ranking bills 3 credits. Each page fetched and cleaned with fetchContent adds 1 credit. A deep search bills 3 credits for the job plus 5 credits per page scraped, because a platform-aware scrape is real browser work rather than a fetch.

Full rate card

Turning it on

  1. 1Nothing per-tenantSearch is available on the same Bearer key as every other endpoint.
  2. 2Start shallowA plain ranking is the cheapest thing here. Add `fetchContent` only when you actually need the text.
  3. 3Go deep for real readsdepth: "deep" returns a jobId; poll it or hand it a completion webhook rather than holding a request open.
  4. 4Feed it forwardThe URLs a search returns are the input to extract, crawl or ETL — that is the usual pipeline.

At a glance

The contract, in the fewest rows that say it

PropertyTwin Browser
EndpointPOST /api/v1/search
Depths"shallow" (sync) · "deep" (202 job)
Results`count` 1–20, default 10
Fetch`fetchContent` + `topN` 1–10, default 3
Sourcesweb · discussions · news · faq · hackernews
Deep resultGET /api/v1/jobs/{id}

Limits

Where it stops, and what it deliberately does not do

A capabilities page with no limits section is a brochure. These are the ceilings, the defaults that will surprise you, and the things this capability is not.

Limits and defaults

  • `count` is capped at 20 and `topN` at 10.
  • A search backend must be configured for the deployment; if it is not, the endpoint answers 503 rather than returning a degraded result.
  • Deep search is asynchronous only. There is no synchronous deep read.
  • Result content is cleaned page text, not a structured schema — run extract on a URL when you need typed fields.

What it does not do

  • It does not index the web itself. It blends and dedupes upstream sources; the ranking is not Twin's own.
  • It does not act on results. Finding a page and doing something on it are two calls.
  • It does not persist anything. If you want the results searchable later, load them through the ETL pipeline.
  • It does not bypass a paywall or a login on a result it fetches.

FAQ

Questions about web search & deep search

When should I use deep search instead of shallow?
When you need the CONTENT of several results and the read is longer than you want to hold a request open for. Shallow with fetchContent handles a few pages inline; deep submits a job that scrapes the top matches platform-aware and returns through GET /api/v1/jobs/{id}.
What does the `source` field tell me?
Which cluster a result came from — web, discussions, news, faq or hackernews. Results are deduped by URL across clusters, so the tag is how you weight a forum thread differently from a news item.
Is the content it returns structured?
No — it is cleaned page text. For typed fields, take the URL and call POST /api/v1/extract with a schema or a template, which has a zero-model path.
What happens if search is not configured?
The endpoint returns 503 with an error rather than silently degrading. That is deliberate: a search that quietly returns nothing is worse than one that says it is unavailable.

Keep reading

The rest of the platform

The capabilities this one works with, the tools that expose it, the guides that use it end to end, and the vocabulary behind it.

Structured extraction

Ask for fields or a JSON schema and get typed data back — or match a per-host template, expand a row selector, or capture the page's own XHR, and pay no model cost at all.

ETL & semantic query

Extract, clean, chunk, embed and load any source — URL, HTML or raw text — into a queryable store, then search it with a natural-language query for a flat credit.

Site mapping & crawl

Discover a site's URLs from its sitemap, robots and a shallow link scan for a flat fee — then run a bounded, resumable, robots-respecting crawl that can extract per page.

Tools that expose it

searchdeep_searchextract

Put your agent to work. Keep the decision.

Start free. Hand your agent a goal on a site you authorize, set the guardrails, and let the first successful run compile the skill every run after it replays.

Start freeRead the docs