Search.

POST https://metasearch.sh/api/v1/search
Authorization: Bearer ms_live_…
Content-Type: application/json
Idempotency-Key: 0b7e…            (optional)

Create a key in the dashboard; the key search login stores for search-cli is the same kind of key. An unknown or revoked key returns 401 invalid_api_key.

Request body#

The body is a JSON object. A field not listed here is rejected with 400 invalid_request, never ignored.

Filters#

A filter is never dropped silently. Without providers, the router skips engines that cannot honour every filter you sent. A pinned engine that cannot honour one returns 400 filter_unsupported with the engines that can in supported_by. The manifest lists the filters each engine accepts per mode. An unknown filter name is a 400 invalid_request.

{
  "query": "retrieval augmented generation evaluation",
  "mode": "academic",
  "providers": ["exa", "serper"],
  "count": 10,
  "filters": { "freshness": "year", "exclude_domains": ["medium.com"] }
}

Modes#

The engines behind each mode are on Providers & modes.

Routing#

With no mode, auto routing picks one first; it never picks deep, and picks social only when the query names a platform: X, Twitter, TikTok, Instagram or YouTube. Send a mode to skip it.

Without providers, engines are tried in the mode's priority order, healthy engines first, until one returns at least one result: at most 3 attempts, 4 in URL modes. If no engine can serve the mode you get 503 no_provider_for_mode.

A named engine is checked strictly: an unknown name is 400 unknown_provider (with valid_providers), one that does not serve the mode is 400 provider_mode_mismatch (with supported_modes), and one that is switched off or failing is 503 provider_not_available.

Idempotency#

Send an Idempotency-Key header (1 to 255 characters of A-Z a-z 0-9 _ . : -) to make a retry safe. Keys are scoped to your organisation and kept for 24 hours.

• Same key and same body after a 200: the stored response, with replayed: true and the header Idempotent-Replayed: true. A replay is not charged.
• Same key while the first request is still running: 409 idempotency_in_progress; retry after the Retry-After seconds.
• Same key with a different body: 422 idempotency_mismatch.
• A request that ended in an error releases its key.

Response#

Every response, errors included, carries an X-Request-Id header with the same value as request_id.

No results#

If every engine tried returns nothing, the response is still a 200, with results: [], charged_micros: 0, the message "No provider returned results; nothing was charged." and each attempt's outcome in routing.attempts.

Time limits#

Each mode has one deadline shared by all its attempts. The manifest gives it as deadline_ms. Set your client timeout above it; 90 seconds covers every mode.