Quickstart.

From sign-in to first results. There is no SDK to install: it is one HTTPS endpoint.

01Sign in

Go to metasearch.sh/login and enter your email. We send you a sign-in link; there is no password.

02Create a key

In the dashboard, top up from $5 first (calls draw on a prepaid balance), then create an API key. It starts with ms_live_. You can reveal it again from the dashboard later, so there is no need to paste it anywhere but your environment.

$ export METASEARCH_API_KEY="ms_live_…"

03Make a call

request

$ curl https://metasearch.sh/api/v1/search \
    -H "Authorization: Bearer $METASEARCH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "solid-state batteries", "count": 5}'

response

{
  "request_id": "6f1c2a9e-4d0b-4b7e-9a51-…",
  "mode": "auto",
  "provider": "serper",
  "results": [
    {
      "title": "Solid-state batteries clear a manufacturing hurdle",
      "url": "https://…",
      "snippet": "…",
      "published": "2026-10-28"
    }
  ],
  "routing": {
    "auto": {
      "mode": "general",
      "source": "model",
      "reason": "A general web question (p 0.91); used general.",
      …
    },
    "merge": "chain",
    "served_by": "serper",
    "providers": ["serper"],
    "fell_back": false,
    "attempts": [
      { "provider": "serper", "outcome": "ok", "latency_ms": 640, "charged_micros": 1500 }
    ]
  },
  "billing": {
    "reserved_micros": 3000,
    "charged_micros": 1500,
    "balance_micros": 998500,
    "charged_usd": 0.0015,
    "balance_usd": 0.9985
  }
}

With no mode the server picks one and reports it in routing.auto; with no providers it goes to the first available engine for that mode. The Search reference lists every field.

04Read the charge

billing.charged_usd is what this call cost and billing.balance_usd is what is left. Before dispatch the call held reserved_micros against your balance, its most expensive outcome; the charge is never higher, and the difference went back to your balance. An agent can read these two fields after every call and stop before it runs out. Billing explains the rules.

When your credit runs low, top up from the dashboard. Prices for each engine and mode are on /pricing.

From code#

python (requests)

import os, requests

r = requests.post(
    "https://metasearch.sh/api/v1/search",
    headers={"Authorization": f"Bearer {os.environ['METASEARCH_API_KEY']}"},
    json={"query": "solid-state batteries", "mode": "news", "count": 5},
    timeout=90,
)
data = r.json()
if not r.ok:
    raise SystemExit(f"{data['error']}: {data['message']} (request {data.get('request_id')})")

print(data["routing"]["served_by"], data["billing"]["charged_usd"])
for hit in data["results"]:
    print(hit["title"], hit["url"])

typescript (fetch)

const res = await fetch("https://metasearch.sh/api/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.METASEARCH_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "solid-state batteries", mode: "news", count: 5 }),
  signal: AbortSignal.timeout(90_000),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.message}`);

console.log(data.routing.served_by, data.billing.charged_usd);
for (const hit of data.results) console.log(hit.title, hit.url);

Every error body carries error, message and retryable; see Errors.

From the terminal#

With search-cli 0.10 or later, search login opens your browser, you approve the request, and the CLI stores a key for this machine. From then on, engines you have no key of your own for go through your metasearch.sh account.

$ brew install paperfoot/tap/search-cli
$ search login
$ search -m news -q "solid-state batteries" --json

From an agent#

The same key works with the hosted MCP server, so Claude Code, Cursor or Codex can call metasearch as a tool. Setup is on MCP server.