SERP

Overview & Purpose

GET /serp answers a different question than the other endpoints: not “what’s on this page?” but “what does the search engine say?” It queries the engine configured on the orchestrator (Google, Brave, or DuckDuckGo — not a client-selectable parameter) and returns parsed organic results, not raw search-engine HTML. Use it when you need search results themselves — rank tracking, competitive research, “what’s currently ranking for X” — rather than the content of a page you already have the URL for. If you already have a URL, use Scrape instead. Prerequisites: a valid API key. No special scope required.

Best practices

Choose mode deliberately. fast returns organic results only — cheaper and quicker. full (the default) adds the knowledge graph, People Also Ask, related searches, sitelinks, and result attributes when the engine provides them. Use fast if you only need ranked links.
Set output only when you need page content. Enriching results with html, clean_html, or links fetches each result’s page and is billed as one ordinary scrape per result attempted — leave it unset for metadata-only results.
Not every engine returns every field. Knowledge graph, People Also Ask, sitelinks, and an estimated result total are all best-effort — treat their absence as normal, not an error.
Use tbs for freshness-sensitive queries (qdr:d, qdr:w, qdr:m) instead of filtering stale results client-side.
Localize with country/language rather than embedding location terms in query — it’s more reliable and doesn’t cost extra query length.

Practical Implementation Example

Scenario: get the top ranked pages for a keyword, then pull cleaned page content for each result in the same request.

curl -G "https://api.scrapeswitch.com/serp" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "query=best running shoes" \
  --data-urlencode "mode=fast" \
  --data-urlencode "output=clean_html,links"

import os
import httpx

response = httpx.get(
    "https://api.scrapeswitch.com/serp",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"query": "best running shoes", "mode": "fast", "output": "clean_html,links"},
    timeout=60.0,
)
response.raise_for_status()
results = response.json()["organic"]
for result in results:
    print(result["position"], result["title"], result["link"])

const params = new URLSearchParams({
  query: "best running shoes",
  mode: "fast",
  output: "clean_html,links",
});

const response = await fetch(`https://api.scrapeswitch.com/serp?${params}`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});

const { organic } = await response.json();
organic.forEach((r) => console.log(r.position, r.title, r.link));

Error codes

Code	When you receive it
`400`	Malformed query parameters.
`422`	An invalid parameter value — e.g. an empty `query`, an invalid `country`/`language` code, `num_results` out of range, or an invalid `tbs`.
`429`	The search engine’s own rate limit was reached. Retry after a short delay.
`502`	The search engine returned an invalid or blocked response.
`503`	The search engine is unavailable.
`504`	The search request timed out.

Get started

Endpoints

Teams

Billing

Recipes

Monitoring

Overview & Purpose

Best practices

Practical Implementation Example

Error codes

Reference Links

​Overview & Purpose

​Best practices

​Practical Implementation Example

​Error codes

​Reference Links

Overview & Purpose

Best practices

Practical Implementation Example

Error codes

Reference Links