Skip to content

New AI assistant answers: ChatGPT, Gemini, Copilot and AI Mode by API

SerpKite
Get API key
Docs menu / Common parameters

Common parameters

Every request parameter the SerpKite search endpoints accept, with types, defaults and allowed values, grouped by what they control.

View as Markdown

All search endpoints under /v1 share one parameter set, with snake_case names. You send it as a JSON object on POST, or as a query string on GET with the same names. Only q is required. Each endpoint’s reference page lists exactly the parameters it accepts; for example /v1/place and /v1/reviews take place_id (or cid, fid) instead of q, and /v1/webpage takes url.

All parameters

ParameterTypeDefaultDescription
q requiredstringThe search query. Required. Up to 2,048 characters.
countrystringusCountry to search from, as a two-letter ISO code (us, gb, de, in…). Defaults to the country a location ends in.
languagestringenInterface language, as a language code with an optional region (en, de, pt-BR, zh-TW…).
locationstringCanonical location for local results, e.g. "Austin, Texas, United States". Ending in a country name also sets country.
uulestringGoogle-encoded location string. Use instead of location if you already have it.
llstringMaps and places: search the map at a point and zoom, as "@lat,lng,zoomz", e.g. "@52.52,13.40,14z" (zoom defaults to 14z), wherever the request comes from. Overrides location.
numinteger10Results per call, 1–100. Up to 10 returns one page of 10 (1 credit); above 10 on search and news fetches whole pages as a depth bundle, and 100 costs 7 credits instead of 10. On images a page holds up to 100 images and num (default all) is how many of them come back.
pageinteger1Results page, 1–10. Each page is billed separately.
timestringRestrict to recent results. Shorthand for tbs=qdr:*. One of: hour, day, week, month, year.
tbsstringRaw Google tbs filter, e.g. qdr:w2 or cdr:1,cd_min:1/1/2026,cd_max:1/31/2026. Overrides time.
devicestringdesktopWhich SERP layout to fetch. One of: desktop, mobile.
safestringoffSafeSearch filtering. One of: off, active.
autocorrectbooleantrueLet Google correct misspelled queries. Set false to search the exact text.
formatstringjsonResponse format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: json, compact, markdown.
fieldsstringComma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens.
include_contentinteger0Also fetch the top N result pages (0–5) as Markdown. +1 credit per page.
adsbooleanfalseInclude sponsored results in ads.
max_ageintegerAccept a cached result up to this many seconds old. Cache hits cost 50% of the credits.
enginestring or arraygoogleWhich search providers may answer. google is Google only (SerpKite still retries Google internally); auto falls back to other providers when Google is blocked or times out; consensus (search only) asks several independent indexes in parallel, merges the results by URL, ranks them by agreement and lists each result's sources, at the sum of one page per provider that returned results; a provider name or a list (e.g. google,brave) restricts the request to those. meta.engine names the provider that answered. One of: google, auto, consensus, brave, bing, yahoo, duckduckgo, mojeek, wikipedia, yandex.
place_idstringPlace and reviews: Google place ID (from maps/places results). Or pass cid or fid instead.
cidstringPlace and reviews: Google customer ID of the place (decimal).
fidstringPlace and reviews: Google feature ID of the place ("0x…:0x…").
oidstringPlace: Yandex Maps organisation ID (digits, the number in yandex.ru/maps/org/…/<oid>/). Implies engine=yandex; not combined with place_id, cid or fid.
sortstringmost_relevantReviews: sort order. Only most_relevant is served: Google shows other orders only to signed-in visitors, so they return 400 (not charged). One of: most_relevant, newest, highest_rating, lowest_rating.
page_tokenstringReviews: next_page_token from the previous page, unchanged (bound to the place and sort). Paging reaches the first 10 reviews of a place (what Google shows logged-out visitors).
urlstringWebpage: page URL to fetch.
include_htmlbooleanfalseWebpage: also return the raw HTML.
domainstringRank: domain to find, e.g. example.com (subdomains match).
include_linksbooleanfalseWebpage: also return the page's outbound links (url, text).
include_imagesbooleanfalseWebpage: also return the page's image URLs. Shopping: data: thumbnails on cards with no image URL.
include_domainsstring[]Only results from these sources, up to 20: a domain (example.com, subdomains match), a path prefix (github.com/org) or a TLD (.gov). Compiled to site: operators and enforced on the results. Search, news, images, videos.
exclude_domainsstring[]Drop results from these sources, up to 20, same formats as include_domains. Search, news, images, videos.
boost_domainsstring[]Move results from these sources to the top without filtering out the rest, up to 20. Search and news.
start_datestringOnly results published on or after this date (YYYY-MM-DD). Google's custom date range; can't be combined with time or tbs.
end_datestringOnly results published on or before this date (YYYY-MM-DD).
highlightsbooleanfalseWith include_content: return up to 3 query-ranked passages (~600 characters each) per fetched page in results[].highlights instead of the whole page. No extra credits.
include_answerbooleanfalseAdd a short answer written by Claude over the results, with [n] citations, in answer.text and answer.citations. +2 credits (+4 with include_content, when it reads the pages), refunded (with a meta.warnings entry) when the model fails. Search and news.

ll (a map point and zoom) applies only to /v1/maps and /v1/places. engine defaults to google (Google only); auto, a single provider or a list allows fallback engines on search, news, images and videos. See Search providers.

Sending parameters

The two requests below are equivalent:

curl https://api.serpkite.com/v1/search \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"coffee grinder","country":"de","language":"de","num":20,"time":"month"}'

Numbers and booleans are accepted either as JSON numbers and booleans or as strings ("num": "20", "autocorrect": "false"), so query strings and loosely typed clients both work. Invalid values return 400 invalid_request with a message naming the parameter, and are never billed.

The body must be a single JSON object. To run many queries at once, queue them with POST /v1/batches (up to 100 per call, at half price).

Strict validation

Unknown parameters are rejected, never silently ignored, so a typo can’t quietly fall back to a default (a misspelled country would otherwise search from the US). The API answers 400 invalid_request, names the parameter and, when it recognises a name used by other SERP APIs, tells you the replacement:

400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "unknown parameter \"gl\": use country",
    "request_id": "req_01J8ZK9W3HC2D"
  }
}
If you send Use instead
gl country
hl language
placeId place_id
sortBy sort
nextPageToken page_token
mode POST /v1/batches
type The endpoint path, e.g. /v1/news instead of "type": "news"

A JSON array body is rejected the same way (body must be a JSON object; to run many queries use POST /v1/batches). None of these errors is billed.

Query

q is the search query, 1 to 2,048 characters. Google operators work as they do on google.com: site:, -exclude, "exact phrase", filetype:, intitle: and so on.

ParameterTypeDefaultDescription
q requiredstringThe search query. Required. Up to 2,048 characters.

Location and language

country picks the country Google searches from and language the interface language. location narrows results to a city or region, which matters for local packs, maps and anything with local intent. uule is the pre-encoded form of a location if you already have one. See Localization for the full list of codes and how they interact.

ParameterTypeDefaultDescription
countrystringusCountry to search from, as a two-letter ISO code (us, gb, de, in…). Defaults to the country a location ends in.
languagestringenInterface language, as a language code with an optional region (en, de, pt-BR, zh-TW…).
locationstringCanonical location for local results, e.g. "Austin, Texas, United States". Ending in a country name also sets country.
uulestringGoogle-encoded location string. Use instead of location if you already have it.
llstringMaps and places: search the map at a point and zoom, as "@lat,lng,zoomz", e.g. "@52.52,13.40,14z" (zoom defaults to 14z), wherever the request comes from. Overrides location.

Paging and depth

page walks through result pages, one credit each. num above 10 fetches deeper results in one call on /v1/search and /v1/news, and num=100 is a bundle of 10 pages for 7 credits. See Pagination and depth.

ParameterTypeDefaultDescription
numinteger10Results per call, 1–100. Up to 10 returns one page of 10 (1 credit); above 10 on search and news fetches whole pages as a depth bundle, and 100 costs 7 credits instead of 10. On images a page holds up to 100 images and num (default all) is how many of them come back.
pageinteger1Results page, 1–10. Each page is billed separately.

Filters

time is a friendly shorthand for recency. tbs passes Google’s raw filter string through when you need something time doesn’t cover, like a custom date range. If you send both, tbs wins.

ParameterTypeDefaultDescription
timestringRestrict to recent results. Shorthand for tbs=qdr:*. One of: hour, day, week, month, year.
tbsstringRaw Google tbs filter, e.g. qdr:w2 or cdr:1,cd_min:1/1/2026,cd_max:1/31/2026. Overrides time.
devicestringdesktopWhich SERP layout to fetch. One of: desktop, mobile.
safestringoffSafeSearch filtering. One of: off, active.
autocorrectbooleantrueLet Google correct misspelled queries. Set false to search the exact text.
time Equivalent tbs
hour qdr:h
day qdr:d
week qdr:w
month qdr:m
year qdr:y

A custom date range is easiest with start_date and end_date (YYYY-MM-DD), which build that tbs for you; raw tbs such as cdr:1,cd_min:1/1/2026,cd_max:3/31/2026 works too.

time works on search, news, images, videos and shopping; scholar, maps, places, patents and autocomplete reject it with a 400 instead of returning unfiltered results. When a request falls back from Google to another engine (engine), the time window goes along: an engine without that window (Bing web search has no past hour, Yahoo no past year) is skipped rather than answering unfiltered. With an explicit engine=bing that combination is a 400.

Domain filters (include_domains, exclude_domains, boost_domains) and the date range are described in Search filters.

ParameterTypeDefaultDescription
include_domainsstring[]Only results from these sources, up to 20: a domain (example.com, subdomains match), a path prefix (github.com/org) or a TLD (.gov). Compiled to site: operators and enforced on the results. Search, news, images, videos.
exclude_domainsstring[]Drop results from these sources, up to 20, same formats as include_domains. Search, news, images, videos.
boost_domainsstring[]Move results from these sources to the top without filtering out the rest, up to 20. Search and news.
start_datestringOnly results published on or after this date (YYYY-MM-DD). Google's custom date range; can't be combined with time or tbs.
end_datestringOnly results published on or before this date (YYYY-MM-DD).

Output

These parameters change the shape and size of the response, not the search itself. See Output formats and Page content.

ParameterTypeDefaultDescription
formatstringjsonResponse format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: json, compact, markdown.
fieldsstringComma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens.
include_contentinteger0Also fetch the top N result pages (0–5) as Markdown. +1 credit per page.
highlightsbooleanfalseWith include_content: return up to 3 query-ranked passages (~600 characters each) per fetched page in results[].highlights instead of the whole page. No extra credits.
adsbooleanfalseInclude sponsored results in ads.

Cost and delivery

max_age lets you accept a recent cached result for half the credits. For work that doesn’t need an answer right now, send the same request bodies to POST /v1/batches, also at half price, and get the results by polling or webhook. See Caching.

ParameterTypeDefaultDescription
max_ageintegerAccept a cached result up to this many seconds old. Cache hits cost 50% of the credits.
enginestring or arraygoogleWhich search providers may answer. google is Google only (SerpKite still retries Google internally); auto falls back to other providers when Google is blocked or times out; consensus (search only) asks several independent indexes in parallel, merges the results by URL, ranks them by agreement and lists each result's sources, at the sum of one page per provider that returned results; a provider name or a list (e.g. google,brave) restricts the request to those. meta.engine names the provider that answered. One of: google, auto, consensus, brave, bing, yahoo, duckduckgo, mojeek, wikipedia, yandex.

Place, Reviews and Webpage

These endpoints take an identifier or URL instead of q. /v1/place and /v1/reviews need one of place_id, cid or fid, taken from a maps or places result. Reviews page with a cursor: pass next_page_token from the previous response as page_token. See Pagination and depth.

ParameterTypeDefaultDescription
place_idstringPlace and reviews: Google place ID (from maps/places results). Or pass cid or fid instead.
cidstringPlace and reviews: Google customer ID of the place (decimal).
fidstringPlace and reviews: Google feature ID of the place ("0x…:0x…").
sortstringmost_relevantReviews: sort order. Only most_relevant is served: Google shows other orders only to signed-in visitors, so they return 400 (not charged). One of: most_relevant, newest, highest_rating, lowest_rating.
page_tokenstringReviews: next_page_token from the previous page, unchanged (bound to the place and sort). Paging reaches the first 10 reviews of a place (what Google shows logged-out visitors).
urlstringWebpage: page URL to fetch.
include_htmlbooleanfalseWebpage: also return the raw HTML.
include_linksbooleanfalseWebpage: also return the page's outbound links (url, text).
include_imagesbooleanfalseWebpage: also return the page's image URLs. Shopping: data: thumbnails on cards with no image URL.

Which endpoint takes what

Each endpoint page lists exactly the parameters it supports:

EndpointMethod and pathCreditsReturns
Google SearchPOST /v1/search1request, results, answer_box, ai_overview, knowledge_graph, people_also_ask, related_searches, top_stories, places, ads, meta
Google NewsPOST /v1/news1request, results, meta
Google ImagesPOST /v1/images1request, results, meta
Google VideosPOST /v1/videos1request, results, meta
Google MapsPOST /v1/maps1request, results, meta
Google PlacesPOST /v1/places1request, results, meta
Google Place DetailsPOST /v1/place1request, results, meta
Google ReviewsPOST /v1/reviews1request, results, next_page_token, meta
Google ShoppingPOST /v1/shopping1request, results, meta
Google ScholarPOST /v1/scholar1request, results, meta
Google PatentsPOST /v1/patents1request, results, meta
Google AutocompletePOST /v1/autocomplete0.5request, results, meta
Webpage to MarkdownPOST /v1/webpage1request, url, status_code, markdown, text, metadata, meta
Custom Search (CSE-compatible)GET /customsearch/v11kind, searchInformation, items, queries
AnswerPOST /v1/answer3–10answer, citations, results
ExtractPOST /v1/extract1results
MapPOST /v1/map1results
CrawlPOST /v1/crawl1a task (202, poll or webhook)
ResearchPOST /v1/research30–200a task (202, poll or webhook)
MonitorsPOST /v1/monitors1results
ChatGPTPOST /v1/chatgpt4text, markdown, sources, search_queries, products, mentions
GeminiPOST /v1/gemini3text, markdown, sources, search_queries, products, mentions
Copilot SearchPOST /v1/copilot3text, markdown, sources, search_queries, products, mentions
Google AI ModePOST /v1/ai_mode2text, markdown, sources, search_queries, products, mentions
Brave AIPOST /v1/brave_ai2text, markdown, sources, search_queries, products, mentions

Last updated: 2026-10-21