# metasearch.sh

> One API key and one prepaid balance for web search, news, academic, scraping and X search engines. Leave the mode out and the router picks it, or name the mode and the engines yourself. A call in academic costs one flat price whichever engine answers; every other call is billed at 1.5x the answering engine's list price, at least $0.0001 a call. Failed, timed-out and empty calls cost nothing. Top up from $5 before the first call.

Endpoint: `POST https://metasearch.sh/api/v1/search` with `Authorization: Bearer ms_live_...` and a JSON body such as `{"query": "rust async runtimes"}`. Create a key at https://metasearch.sh/dashboard.

The mode defaults to `auto`: the router picks one mode before the call, bills that mode, and reports its choice and the reason in `routing.auto`. Auto never picks deep. It picks social (from $0.00282 a call) only on a platform cue: "tweet", "Twitter", "on X", an x.com link or an @handle for X; "on tiktok" or "tiktok videos"; "instagram reels" or "on instagram"; "youtube videos", "youtube comments" or "on youtube". A named platform is searched alone, one call. Code such as @types/node, @media or Twitter cards, and questions about the platforms themselves (the YouTube API, TikTok's stock), do not count.
Results are reranked for relevance by default (`routing.reranked`; send `rerank: false` to keep the engines' order). Auto routing and reranking add no charge.
An identical request repeated within its mode's cache time is answered from the stored result at the same price, marked `routing.cached: true` with `cached_at`; send `fresh: true` to search again. An attempt marked `escalated: true` is a cheap engine's list the router set aside to ask a better engine: it is never charged.

## Modes

- `auto` (text or url query, the default): the router picks the mode from the query and reports why in `routing.auto`.
- `general` (text query): Any web lookup not covered by a more specific mode. Not for: Papers (academic), current events (news), a named person (people).
- `news` (text query): Current events and recent coverage.
- `academic` (text query): Papers and studies on a topic, found semantically. Not for: Citation counts and PDF links: use scholar.
- `people` (text query): A named person: their role, employer, LinkedIn profile. Served by Exa alone; if Exa is unavailable, search general for the name and employer. Not for: What people are saying about a topic: use social.
- `deep` (text query): Wider coverage on a hard question. Slower and dearer than general. Not for: Routine lookups: general costs a fraction of this.
- `extract` (url query): One page as markdown. Tries our own fetch first, then rendering services. A Reddit or Hacker News thread, or a TikTok, Instagram, YouTube, Facebook or Threads post URL, is read by that source: the post, its stats and its comments or transcript. Not for: Finding pages: search first, then extract the URL you want.
- `scrape` (url query): Alias of extract.
- `similar` (url query): Pages resembling a given page: competitors, related coverage.
- `scholar` (text query): Google Scholar records: citation counts, versions, PDF links.
- `patents` (text query): Patent filings.
- `images` (text query): Pictures. Returns imageUrl (the image) and url (the page it sits on). Served by Serper, with SerpApi as the fallback on the hosted API.
- `places` (text query): Businesses and physical locations, with addresses.
- `social` (text query): Posts and videos on X, TikTok, Instagram and YouTube, with views, likes, comments and authors. Name the platform in the query ("on tiktok", "instagram reels", "youtube videos", "on X") to search only there; otherwise X and the one platform likeliest to hold the answer are searched together. Put X handles, without @, in include_domains to limit X authors. Extract a TikTok, Instagram, YouTube, Facebook or Threads post URL for its caption, stats, transcript where there is one, and top comments. Not for: Discussion threads (community), reporting (news).
- `community` (text query): What real people say about a topic: Reddit posts and Hacker News stories, with scores or points, comment counts and authors. Put r/<subreddit> in the query to search one subreddit (cheapest); without one, all of Reddit is searched. Extract a Reddit thread or news.ycombinator.com/item URL for the whole thread, every comment in order with its author, score and depth. Not for: X, TikTok, Instagram and YouTube posts (social), reporting (news).

## Pricing

- A call without providers in academic costs one flat price, whichever engine answers. Every other call pays the answering engine's list price × 1.5, at least $0.0001 a call.
- Pin an engine with providers and you pay that engine's rate.
- Failed, timed-out and empty calls are not charged.
- A repeat of the same request shortly after is answered from the stored result at the same price, with no wait; send fresh: true to search again.
- Before a call we hold the most it can cost, then refund the difference the moment it ends. Without providers, that is the largest max among the engines the router may try, or in academic its flat price.
- When one call asks several engines, you pay for each engine that returned results.
- Auto routing and relevance reranking add no charge. Auto never picks deep. It picks social (from $0.00282 a call) only on a platform cue: "tweet", "Twitter", "on X", an x.com link or an @handle for X; "on tiktok" or "tiktok videos"; "instagram reels" or "on instagram"; "youtube videos", "youtube comments" or "on youtube". A named platform is searched alone, one call. Code such as @types/node, @media or Twitter cards, and questions about the platforms themselves (the YouTube API, TikTok's stock), do not count.
- Credits never expire while your account is open.
- Top up any whole amount from $5 to $1,000. No subscription.

One price per mode for a call without providers. A flat price is the same whichever engine answers; pin an engine with providers and you pay that engine's rate. Failed calls are free. For the other modes: the lowest typical price per call (10 results) among the engines enabled now, and what a call without providers holds before it runs (the largest max among the engines the router may try; the rest is refunded):

- `general`: from $0.00075 (jina); without providers holds $0.0255 (tries serper, exa, jina)
- `news`: from $0.0015 (serper); without providers holds $0.0075 (tries serper, brave, linkup)
- `academic`: $0.009 a call, the same whichever engine answers (tries serper, exa, perplexity)
- `people`: from $0.0105 (exa); without providers holds $0.0255 (tries exa)
- `deep`: from $0.0015 (serper); without providers holds $0.033 (tries exa, serper, brave)
- `extract`: from $0.000375 (jina); without providers holds $0.1575 (tries direct, jina, firecrawl)
- `similar`: from $0.0105 (exa); without providers holds $0.0255 (tries exa)
- `scholar`: from $0.0015 (serper); without providers holds $0.003 (tries serper)
- `patents`: from $0.0015 (serper); without providers holds $0.003 (tries serper)
- `images`: from $0.0015 (serper); without providers holds $0.003 (tries serper)
- `places`: from $0.0015 (serper); without providers holds $0.003 (tries serper)
- `social`: from $0.00282 (tiktok, instagram, youtube); without providers holds $0.23064 (tries xai, tiktok)
- `community`: from $0.00075 (hackernews, reddit); without providers holds $0.00639 (tries reddit, hackernews)

Full price list with sources: https://metasearch.sh/pricing

- [metasearch.sh vs Tavily](https://metasearch.sh/compare/tavily): Tavily alternative: Tavily API pricing compared
- [metasearch.sh vs Exa](https://metasearch.sh/compare/exa): Exa API pricing compared: Exa search through one key
- [metasearch.sh vs SerpApi](https://metasearch.sh/compare/serpapi): SerpApi alternative: Google results without a monthly plan

## Docs

- [Quickstart](https://metasearch.sh/docs/quickstart): sign in, create a key, make a first call in curl, Python or TypeScript
- [Search API](https://metasearch.sh/docs/api/search): request fields, filters, routing and fallback, fused results, the response
- [Errors](https://metasearch.sh/docs/api/errors): every error code, its HTTP status and whether to retry
- [Billing](https://metasearch.sh/docs/api/billing): how a call is held, charged and refunded; spend caps; top-ups, auto-recharge and promo codes
- [Usage API](https://metasearch.sh/docs/api/usage): read your organisation's spend and request log with an API key
- [Organisations and roles](https://metasearch.sh/docs/organisations): a shared balance and keys; owner, admin, member and viewer; invites
- [Providers and modes](https://metasearch.sh/docs/api/providers): which engines serve each mode, and which filters each honours
- [MCP server](https://metasearch.sh/docs/mcp): connect an assistant to https://metasearch.sh/mcp: sign in and choose the organisation that pays, or send an API key
- [MCP in Claude](https://metasearch.sh/docs/mcp/claude): claude.ai, Claude Desktop and mobile, Claude Code, the Claude plugin and the Messages API
- [MCP in ChatGPT](https://metasearch.sh/docs/mcp/chatgpt): add metasearch.sh to ChatGPT as a custom MCP server
- [MCP in Codex](https://metasearch.sh/docs/mcp/codex): codex mcp add, then codex mcp login
- [MCP in Cursor](https://metasearch.sh/docs/mcp/cursor): the Add to Cursor link or mcp.json
- [MCP in VS Code and Copilot](https://metasearch.sh/docs/mcp/vscode): the install link, code --add-mcp or mcp.json
- [MCP in Gemini CLI](https://metasearch.sh/docs/mcp/gemini): the extension, or gemini mcp add
- [search-cli](https://metasearch.sh/docs/search-cli): the open-source command-line client, with your own keys or your metasearch.sh account
- [Pricing](https://metasearch.sh/pricing): the price per call for every engine and mode
- [Agent manifest](https://metasearch.sh/api/v1/manifest): JSON with every mode, engine, filter, limit and price, as served now
- [Everything in one file](https://metasearch.sh/llms-full.txt): the full reference as one markdown document

## search-cli

Install one way, then run `search login` to connect it to your account:

- `brew install paperfoot/tap/search-cli`
- `cargo install agent-search`
- `curl -fsSL https://metasearch.sh/install | sh`

## Optional

- [Updates](https://metasearch.sh/updates): what changed, newest first
- [Status](https://metasearch.sh/status): recent provider checks
- [Terms](https://metasearch.sh/terms) and [Privacy](https://metasearch.sh/privacy)