Auto routing.
Send a query without a mode and the server picks one, tells you why, and puts the most relevant results first. Send a mode and it does exactly what you asked.
Auto mode#
mode defaults to auto. Before anything is reserved or sent to an engine, auto resolves to one real mode, and your reservation and charge are those of that mode. The decision is in every response as routing.auto:
"routing": {
"auto": {
"mode": "news",
"source": "model",
"reason": "Asked about recent events (p 0.97); used news with freshness week.",
"probabilities": { "general": 0.02, "news": 0.97, "academic": 0, … },
"filters_applied": { "freshness": "week" },
"latency_ms": 240
},
"reranked": true,
…
}Three steps, in order. Fixed rules decide the clear cases. If none fires, a small judgement model reads the query and picks a mode when it is confident (source: "model"). Otherwise the search runs as general, with source: "fallback".
The rules#
Checked in this order, ignoring case except for "on X"; the first match decides.
| # | when the query | mode |
|---|---|---|
| 1 | is a single http(s) URL | extract |
| 2 | mentions tweets, Twitter or "on X" (capital X, and not an x-axis), contains x.com/, or has a lone @handle. Code does not count: an email address, an npm scope such as @types/node, a decorator or at-rule such as @property or @media, or Twitter cards and Bootstrap. Also a platform phrase: "on tiktok", "tiktok videos", "instagram reels", "on instagram", "youtube videos", "youtube comments", "on youtube" (not the platform itself: its API, stock, login or a how-to). The named platform is searched alone, one paid call; with no platform named, X and the one platform likeliest to hold the answer, never more than two. "facebook page" or "on Threads" runs as a general search of that site | social |
| 3 | is "similar to", "sites like", "alternatives to", "competitors of" or "more like" followed by a URL (the URL becomes the query) | similar |
| 11 | mentions Reddit, a subreddit such as r/rust (not a unit such as r/min), Hacker News, "on HN", Show HN or Ask HN (not their APIs, stock or logo), or asks what people say or think about something or their experiences with it. A subreddit is searched on its own, the cheapest way; without one, all of Reddit | community |
| 4 | mentions patents or prior art (not patent leather), or a patent number such as US 10123456 or EP1234567 | patents |
| 5 | asks for images, photos, pictures, logos or wallpapers "of" or "for" something, except system images such as Docker, container or VM images | images |
Words such as "near me", "cited by", "paper", "who is" or "latest" are only hints: "news aggregator API" is not a news search and "who is hiring" is not a person search. The model decides those from what the query asks for.
Freshness comes from explicit words only: "today" or "yesterday" sets day; "this week", "latest" or "breaking" sets week; "this month" and "this year" set month and year. It applies only when the search runs in news, social or community(in a general question "today" or "latest" is usually part of a name or a version), never overrides a freshness you sent, and is reported in filters_applied.
What the model decides, and what it never does#
The model chooses among general, news, academic, scholar, people, images, places and patents. It sees the query and nothing else, answers in about a quarter of a second, and is given at most 1.5 seconds; if it is slow or down, the rules' answer or general stands. It never chooses deep or social, which cost several times a general search: ask for those by name. It never sets filters, and it never overrides a mode or engines you sent.
Relevance rerank#
In general, news, academic, scholar, people and deep, when there are at least three results and the request is not pinned to one engine, the model judges how well each result answers the query from its title, snippet and host. The new order weighs that judgement against the engines' own ranking, so a close call keeps the engines' order. Each result then carries extra.relevance (0 to 1) and routing.reranked is true. If the judgement fails, you get the original order and reranked: false. Rerank is free; send rerank: false to turn it off.
Cheapest engine first#
In academic, the router starts with a web search, which finds papers for most research questions. If its list is thin, or the model judges from the titles and snippets that it is not the papers and studies you asked for, the scholarly index is asked next and its results are served instead. You pay only for the list you get. In social with no platform named, the model picks the platforms where the answer is likeliest, at most two. An engine you name is always used as sent.
Page checks in extract#
A fetched page that passes the built-in checks but is short gets one more look: is this the page's content, or a login wall, paywall, cookie notice, CAPTCHA, error page or empty shell? If it is clearly not content, the next engine in the chain is tried, and a page that was not returned is not charged. This check can only send a page onward; it can never accept a page the built-in checks refused.
Hints#
When you send a mode and the query plainly belongs to another (for example academicfor "coffee near me"), the response may carry routing.hints with the suggested mode, its probability and a one-line message. Hints are worked out alongside the search and never change what ran.
Endpoints#
Two endpoints expose the same decisions, so a client that searches on its own (search-cli does) can route and order results the way the server would. Both take your bearer key and are free. Each account gets 300 judgements a minute on each server instance: a route call is one, a rerank is one per result. Past that the answer is 429 rate_limited, and a missing or unknown key is 401 invalid_api_key.
POST https://metasearch.sh/api/v1/route
Authorization: Bearer ms_live_…
{ "query": "latest news on the Fed rate decision" }
→ { "auto": { "mode": "news", "source": "model", "reason": "…" },
"providers": ["serper", "brave", "linkup", …] }mode is optional; send one and it comes back unchanged, with source: "explicit" and that mode's engines. providers is the order the server would try right now: an engine that is switched off or has no key is left out, and one failing its health check moves back.
POST https://metasearch.sh/api/v1/rerank
Authorization: Bearer ms_live_…
{ "query": "postgres advisory lock with pgbouncer",
"results": [ { "id": "a", "title": "…", "snippet": "…", "url": "https://…" }, … ] }
→ { "order": ["c", "a", "b"], "relevance": { "a": 0.91, "b": 0.12, "c": 0.97 },
"model": "metasearch-1", "latency_ms": 260 }1 to 30 results, each with a unique id of up to 64 characters and a url of up to 2,048 characters; the query has the search limit of 2,000 characters. If the judgement is unavailable the response is still a 200, with your order, an empty relevance and model: null, so a client never breaks on it.
Opting out#
Send mode: "general" (or any mode) to skip auto routing, and rerank: false to keep the engines' order. The Search API lists every field.