API changelog
Changes to the SerpKite API contract, newest first. Additive changes ship without notice; anything breaking is announced here in advance.
This page tracks the public API at api.serpkite.com: endpoints, parameters, response fields, errors and billing rules. For changes to Google’s results pages themselves, see the Google SERP changelog.
Compatibility policy. New endpoints, optional parameters and response fields are additive and can appear at any time, so ignore fields you don’t recognize. Removing or renaming anything, or changing what a call costs, is a breaking change: it will get advance notice here and a new API version.
2026-11-13: expanded Google link resolution restored (API 1.16.3)
- Live searches again follow held-back result links in the background for up to two minutes.
POST /v1/resolvereportspendingwithretry_after, thenresolvedwhen Google releases the destination, orfailedwhen it cannot be read in time. Batch jobs and monitors still wait for their links. Once every link resolves, the completed response can enter the result cache. - The Google resolver uses up to four extra page copies to resolve more destinations before the live response. This improves opportunities to resolve links; Google can still delay or refuse them.
2026-11-13: held-back links of live searches (API 1.16.2; superseded by 1.16.3)
- A result link Google holds back past a live request (
link_resolved: false) is no longer followed after the response.POST /v1/resolveanswersfailedfor such links; repeat the search, or run it as a batch job, to get the destination. Batch jobs and monitor runs wait for their links as before, and/v1/resolvestill answers for them.
2026-11-06: rate limits (API 1.16.1)
- The keys of a free account now share its 5 requests per second; before, each key had its own, so extra keys multiplied the free rate. Paid keys keep a budget each.
- MCP tool calls now count exactly like the REST call they stand for.
extract,answer,map,crawlandresearchused to be counted twice, so anextractwith as many URLs as the key’s rate allows was always refused.initialize,tools/listand notifications no longer count. 429 rate_limitedfor a full batch queue or the crawl/research task limit now carriesRetry-After: 30, and the limits hold exactly under concurrent calls.
2026-11-06: Custom Search parity (API 1.16.0)
/customsearch/v1accepts every Custom Search JSON API parameter.exactTerms,excludeTerms,orTerms,hq,fileTypeandlowRange/highRangebecome search operators;cr,lr,sort(date,date:r:…) and the image filters (imgSize,imgType,imgColorType,imgDominantColor,rights) are applied. Before, most of them were ignored.dateRestrictis applied as written (d3was widened to a week),lrandcrrestrict the documents instead of setting the interface language and country, andsafe=high/mediummeanactiveinstead of a400.startcan be any index up to result 100 (start + num - 1 <= 100). A window that spans two Google pages, such asstart=5ornum=3atstart=10, reads both and costs 2 credits; before, it returned only the first page’s part and the next page skipped results.- Errors use Google’s error body on this endpoint:
error.codeis the HTTP status,error.errors[0].reasonGoogle’s reason anderror.statusthe canonical status. SerpKite’s code (formerlyerror.code) is inerror.details[0].reason. - A response without results has no
itemskey, as in CSE.totalResultsis Google’s estimate when shown, otherwise100while more results follow (it used to be the item count, which stopped clients that page up to it). Results whose destination Google held back are flaggedlink_resolved: falseas on/v1/search, with the domain Google showed asdisplayLink.htmlTitleandhtmlSnippetbold the query’s words. /customsearch/v1/siterestrictis served too.- Search snippets no longer end with Google’s “Read more” link text, and image results (
/v1/images, CSEimage.thumbnailLink) now carrythumbnail_url.
2026-11-06: no free daily limit (API 1.15.1)
- Accounts that never bought a pack no longer have a daily limit (it was 1,000 credits per UTC day). Free credits can be spent as fast as the per-second rate limit allows, and requests no longer get
429 daily_limit_reached. The code stays reserved, and the SDKs still don’t retry it. The dashboard no longer shows a daily limit.
2026-11-06: location for AI Mode, Brave’s AI answer and research (API 1.15.0)
/v1/ai_modeand/v1/brave_aitakelocation(anduule): local prompts such as “best pizza near me” answer for that city instead of wherever our exit is.countrydefaults to the location’s country. Brave returns400(free) for a place it can’t find; AI Mode needs a name Google knows (“City, Region, Country”). ChatGPT, Gemini and Copilot don’t take it (400).- AI assistant monitors on
ai_modeandbrave_aitakelocation, so you can track a prompt per city. /v1/researchtakeslocationand runs its searches for that place.- SDKs 0.10.0 add
locationanduuleto the assistant parameters andlocationto research.
2026-11-05: Brave and Yandex apply location (API 1.14.2)
- Brave (search, news, images and videos) and Yandex web search now apply
locationand auulenaming a place, instead of being skipped. A search Google refuses with alocationcan now be answered by Brave for that place (requests withoutengine,engine: "auto", or a key with fallback on), andengine: "brave"or"yandex"with alocationno longer returns400. - An engine that can’t find the place is skipped (a
400when you named it), as before: a result is never answered for the wrong place. Bing, DuckDuckGo, Yahoo, Mojeek and Wikipedia still have no such setting and are skipped the same way.
2026-11-05: location places the whole Google results page (API 1.14.1)
- Google search with
location(or auulenaming a place) now returns results for that place. Before, only the local pack followed it: for queries like “plumber near me” the web results came from wherever our exit happened to be, or turned into generic “near me” pages.
2026-11-05: destinations for held-back links (API 1.14.0)
POST /v1/resolvereturns the destinations of results that came back withlink_resolved: false. SerpKite keeps following those Google redirects after Google’s delay, for up to 2 minutes. A link stillpendingcomes withretry_afterseconds to wait. The call is free.- Batch jobs and monitor runs now wait for those links, up to 2 minutes, before they finish, so their results carry every destination Google releases.
- A live response with such links is now cached once all of them resolve, with every destination filled in. Before, it was never cached.
- SDKs 0.9.0 add
resolve(TypeScript, Python) andResolve(Go), along with thelink_resolvedandunresolved_linksfields.
2026-11-05: every result keeps its place (API 1.13.0)
- Google links results through
google.com/gotoredirects and sometimes holds back where one leads for several seconds. A search result, news story or video whose destination Google hadn’t released by the time we answer used to be dropped, which moved every result below it up a position and marked the responseparse_quality: "partial". That result is now returned in its place withlink_resolved: false. Itslinkis the Google redirect, and itsdomainis the host Google displayed for it (empty when Google showed none). Every other result’slinkis the destination, as before. meta.unresolved_linkscounts such results and is absent when there are none.meta.resolved_urlsisfalsewhile any remain. They no longer make a responsepartial.- A response with unresolved links is not cached, so a later request can get every destination.
- To keep the old behaviour, drop the results with
link_resolved: false. Informat: "compact"they carrylink_resolved: falseanddomain. - Sitelinks, top stories and the knowledge panel’s links are now resolved after the main results, so the main results get Google’s quickest answers. A sitelink or top story still unresolved is left out, as before.
2026-11-04: steadier ChatGPT answers with country (API 1.12.10)
- ChatGPT with
countryset now has three routes to try in that country instead of one, so far fewer of these requests end with503 upstream_timeout. The answer is still asked as a visitor in that country, and the price is unchanged. - A fallback route that had failed for a while could stay unused until our next deploy, even after it recovered. It is now tried again once its cooldown ends. This applies to every endpoint.
2026-11-04: higher free daily limit, fewer refused searches (API 1.12.9)
- The free daily limit is now 1,000 credits per UTC day (was 500) for accounts that never bought a pack. Past it, requests still get
429 daily_limit_reacheduntil 00:00 UTC, and buying any pack still removes it. See Credits and billing. - When Google refuses a query on the first Google sessions we try, it is now tried once more about 1.5 s later on sessions in other countries before the request fails with
503 upstream_blockedor, withoutengine, falls back to another engine. A refused request can take a few seconds longer; a refusal is still never billed. This applies to page 1-3 of realtime requests; batch jobs keep their own retries.
2026-11-04: bot checks try another route (API 1.12.8)
- /v1/webpage and
include_content: a page that turns out to be a bot check is now fetched again through the next route (another proxy pool, then a browser) before the request fails. Before, the first bot check ended the request with503 upstream_blocked. Bot checks are still never billed. - /v1/search: when Google answers a page with no results and no “did not match” notice, the empty result comes back about 1.5 s sooner. A browser retry of such pages almost never found results. The empty result is still free.
2026-11-01: Google’s hidden similar results (API 1.12.7)
- A response has
meta.similar_results_hidden: truewhen Google said it hid results very similar to those shown. This explains short results that have nomissing_pages. - A
numabove 10 that comes back under three quarters of what you asked for with that notice is fetched once more from another session, and twice in a batch job. The longer answer is returned and billed. The extra fetches are free. - A result with that notice is no longer cached, so
max_agecan’t return it later. - An empty later page is now checked from a different session, as intended. Before, the check could return to the session that had just answered, so it couldn’t find the results another session had.
2026-11-01: short results say why (API 1.12.6)
- A
numabove 10 reports pages it couldn’t retrieve inmeta.missing_pages(for example[2]) and setsmeta.parse_qualitytopartial. Before, a page Google refused left a short result markedok, which looked the same as Google having no more results. Withoutmissing_pages, a short result is all Google returned. - Batch jobs ask again for just the missing pages, for up to 2 minutes, before they finish.
- A result with missing pages is no longer cached, so
max_agecan’t return it later. parse_qualityon anumabove 10 covers every page, not only the first.- A page that repeats only links from earlier pages counts as missing and isn’t billed.
page: 2and later return a503instead of an empty result when we couldn’t confirm that Google really ended the results.
2026-10-31: filters that really apply, pages that really change (API 1.12.4)
engine: "bing"on /v1/search:pageandtimework. Bing was answering every page and time window with its first unfiltered page, and those pages were billed.device: "mobile"works onengine: "bing"web search and onengine: "yahoo"web search and news. It used to return an empty result every time.engine: "brave"on /v1/images refusestime,tbsand date ranges (400;engine: "auto"moves to the next engine). Brave’s images ignore them, and the results came back unfiltered.locationanduuleare refused the same way on engines that have no such parameter (Bing, Brave, DuckDuckGo, Yahoo, Mojeek, Wikipedia, Yandex web search), instead of being dropped silently. Google still applies them, and Yandex Maps applieslocation.engine: "yahoo"uses Yahoo’s regional site forcountrywhere it has one: de, fr, es, it, gb, ca, au, br, mx, in, ar, at, ch. Before,countrydidn’t change the results.- /v1/news with
include_domains,exclude_domainsor asite:operator inqreturns news from Google. It used to return only a few results, or none. - /v1/shopping:
positionno longer repeats between pages, so pages now start at 61, 121 and so on. More results now haveimage_url(the first cards of a page carry only an inline thumbnail, which is left out), and every result has alink(Google’s product viewer or shopping page when the card doesn’t link to the merchant). /customsearch/v1returnsqueries.nextPagefor a page with fewer thannumresults. Only an empty page ends the list.engine: "consensus":positiononpage: 2and later continues from the earlier pages instead of restarting at 1.- /v1/chatgpt:
markdownno longer carries backslash escapes (\\.) or the app’s internal link targets, and pages the answer links to are listed insources. - A
fieldsvalue with characters that can’t be in a response key returns400. - A finished crawl’s
progressshows its final counts. /v1/answerwithoutput_schemafills a field for a name, number or date with just that value.- New error
422 target_unavailable: the URL you asked for failed (its site answered with an error such as 404, or its domain doesn’t resolve) on /v1/webpage, and infailed[].error.codeon /v1/extract. These were503 upstream_error, which told clients to retry a request that can’t succeed. Not billed.
2026-10-31: more from the audit (API 1.12.5)
- /v1/shopping: new
include_images: truereturns adata:thumbnail inimage_urlon the cards that have no image URL, usually the first of a page. Off by default, because it can add a few hundred KB to a response. engine: "bing"withdevice: "mobile": a page now holds up to 10 results. Bing’s mobile page shows 3-7, so one call reads up to three of them. Later pages no longer skip results.engine: "bing": Bing’s own video cards no longer appear as results without adomain, which also turnedmeta.resolved_urlsfalse.engine: "yahoo":languagepicks a regional site for de, fr, es, it and pt. Other languages are refused (400;engine: "auto"moves on) whencountryhas no regional site, because Yahoo ignores its language filter.- /v1/news with
include_domainsholding a top-level domain (.gov) next to others no longer comes back empty. /v1/news: aninclude_domainslist with top-level domains (.gov,.edu) reads Google separately for the named domains and for each top-level domain, with and without a URL operator, up to four reads, and merges them in turns for the same 1 credit. A single top-level domain (.edu) finds far more. If Google refuses one read, the others still answer.positioncontinues across pages requested in order: ifpage: 1holds 9 results,page: 2starts at 10 instead of 11. Withinclude_domains, later pages no longer restart at 1.- Requests on the fallback engines through the shared residential pool (Bing, and Brave, Yahoo and DuckDuckGo steps on it) no longer fail with
503when several arrive in the same second. Bing mobile pages come back short less often for the same reason. - A request with no
enginefalls back to Brave and Bing when Google refuses it and a parallel attempt returned an empty page first. It used to answer with that empty page.meta.routelists parallel attempts in route order.
2026-10-30: wider free-use checks
403 account_restrictednow also covers accounts whose requests run in step with several other accounts, every account on a device shared by three or more, and accounts on a disposable email address. Accounts that bought a pack are never affected. It uses request timing, never query text.
2026-10-29: lower prices for AI answers (API 1.12.3)
- Lower prices for AI answers:
/v1/chatgpt4 credits (was 5),/v1/gemini3 (was 5),/v1/ai_mode2 (was 3);/v1/copilot(3) and/v1/brave_ai(2) are unchanged. A cached answer (max_age) still costs half, batches bill the same price, monitors pay the new price per run, and failed, refused and empty answers stay free. The SDKs’ and MCP tools’ descriptions show the new prices.
2026-10-29: MCP assistant tool inputs
- The MCP server’s
chatgpt,gemini,copilot,ai_modeandbrave_aitools now describe their inputs intools/list(prompt,country,languagewhere the assistant takes it,web_searchfor ChatGPT,track). Before, they listedpromptas required but advertised no properties, so some clients could not call them. Calls that already sent these arguments are unchanged, and so is the REST API.
2026-10-28: free credits once per person (API 1.12.2)
- New error
403 account_restricted: free use of an account is paused because another account already signed up from the same device or network. Such an account gets no sign-up, account-linking or monthly free credits, and every charged request gets this error until it buys any pack. Team members you invite are exempt. See Errors and Credits and billing. /v1/geminianswers faster: about 12 seconds at the median, most within 5 to 30 (was about 38, most within 10 to 65)./v1/chatgptand/v1/gemini: an answer still being written at the 90-second budget is no longer lost. The request fails with503 upstream_timeout(free) and a message that the answer is being finished in the background; the same request sent again within 10 minutes returns it, waiting for it if needed, billed once. Batch jobs collect it on their own retry. A Gemini reply that is only its “having a hard time” message is now retried on another connection instead of failing the request outright.- To tell, we keep keyed hashes of the network and a random device cookie (
sk_did) of each sign-in, never the IP address itself: network hashes for 30 days and device hashes for 90. The Privacy Policy and Cookie Policy are updated. The SDKs already raise 403 errors without retrying.
2026-10-28: out-of-credits email
- The first time a request gets
402 insufficient_credits, the account owner now gets an email with the packs and a link to buy one, without having to set an alert. It’s sent once each time the balance runs out, and again only after credits are added. See Spend controls. The API is unchanged.
2026-10-28: clearer free daily limit (API 1.12.1)
429 daily_limit_reachednow says how big the free daily limit is, when it resets and where to remove it: “daily free limit of 500 credits reached; resets 00:00 UTC. Buy any pack at https://app.serpkite.com/billing to remove it”. The code and status are unchanged. The same message reaches batches, crawls, extract, map, answer and the MCP server.- Every endpoint now sends
Retry-Afterwithdaily_limit_reached, counting down to 00:00 UTC. Before, only the search endpoints did. /v1/chatgptanswers faster: about 17 seconds at the median, most within 10 to 30 (was about 22, most within 15 to 40). Thetextandmarkdownno longer carry the questionnaire ChatGPT sometimes appends to a recommendation (its options and “Find my best match” button) or the “View retailer listing” links of its product cards, and a product shown with two offer cards is listed once inproducts.- SDKs 0.8.1 (TypeScript, Go) raise
daily_limit_reachedat once instead of retrying it, as Python already did. Go exportsserpkite.CodeDailyLimit, andError.Retryable()is false for it. - The dashboard shows today’s usage against the free daily limit, with a notice from 80% used. The account owner gets one email the first time the limit is hit each UTC day. See Credits and billing.
2026-10-28: AI assistant answers (API 1.12.0)
New
- Five endpoints ask a public AI assistant a
promptas a logged-out visitor and return its answer (text,markdownwith[n](link)citations), thesourcesit cited or listed (citedflag), thesearch_queriesit ran, theproductsandplacesit showed,related_questionsand themodelit reports:/v1/chatgpt(5 credits;web_search, defaulttrue),/v1/gemini(5),/v1/copilot(Microsoft Copilot Search on Bing, 3),/v1/ai_mode(Google AI Mode, 3) and/v1/brave_ai(Brave Search’s AI answer, 2). They takeprompt(up to 4,000 characters),country,language(not chatgpt),track,include_html,format,fieldsandmax_age. Most answers take 2–65 seconds, depending on the assistant. Failed, refused and empty answers are free; a cache hit withmax_agecosts half; answers are cached for at most an hour. See AI assistants. track: up to 20 brands or domains to check an answer for. Each comes back inmentions(term,mentioned,cited,sources,products,text_position); withformat: "markdown"the answer ends with a## Mentionssection. See AI visibility tracking.- Batches accept the five assistant endpoints, at their full price (the batch lane doesn’t halve AI answers).
- Monitors accept them with
prompt,web_search(chatgpt) andtrack. Every run reports the answer (not only changes) withnew_sources, andmentionswithtrack; themonitor.resultswebhook carriespromptinstead ofq. - /v1/search returns Google’s AI Overview as
ai_overview(text,markdown,sourceswithcited) when the page shows one, at no extra cost. - The MCP server has 23 tools: new
chatgpt,gemini,copilot,ai_modeandbrave_ai. - SDKs 0.8.0: TypeScript
chatgpt,gemini,copilot,aiMode,braveAi; Pythonchatgpt,gemini,copilot,ai_mode,brave_ai; GoChatGPT,Gemini,Copilot,AIMode,BraveAI. They wait at least 120 seconds per attempt and retry only on429.
Perplexity, Grok and Meta AI ask every logged-out visitor to sign in, and we never sign in, so they aren’t offered.
2026-10-28: fewer empty shopping, images and Scholar answers
- /v1/shopping reads Google’s “Popular options” product cards, which queries with a price (“polo shirt 1500 rupees”) get instead of the usual grid. Those used to come back empty; other shopping pages often return more products too.
- /v1/images: when Google refuses an image query, or answers with a page whose image grid only loads in a browser, a request without
engineis answered by Brave (then Bing) instead of503 upstream_blockedor an empty result.meta.enginenames the engine that answered, and it’s billed at that engine’s price.engine: "google"still means Google only. - A query Google refused answers
503 upstream_blockedwith a message that says so andRetry-After: 120. The same request sent again within two minutes gets that answer at once, without asking Google again. Not billed, as before. Rephrase the query or sendengine: "auto". - Shopping requests that Google refused or answered with an empty page come back in about 1 to 3 seconds instead of 10 to 25.
- An empty Google page followed by a failed retry on another route now returns the empty result (200, not billed) instead of
503 upstream_blocked. - /v1/scholar answers far more often: Google Scholar had started refusing most of our requests.
Upcoming, 2026-11-23: batch depth requests billed per page (API 1.9.0)
- In the batch lane, a depth request (
numabove 10 on /v1/search or /v1/news) will cost 0.5 credits per page that returned results, without the 7-credit bundle cap. A batchnum: 100goes from 3.5 to 5 credits;num: 50and below are unchanged (num: 70stays 3.5,num: 80becomes 4). Realtime prices are unchanged:num: 100is still 7. The price is fixed when a batch is queued, so batches queued before 23 November 2026 keep today’s price. Ten Google fetches for 3.5 credits cost us more than they earned on the larger packs.
2026-10-26: failed requests keep their query for 24 hours
- When a request fails (HTTP 5xx) or returns no results, we now keep its query text, options and the steps we tried for 24 hours so we can reproduce and fix the failure, then delete it automatically. The query text of successful requests is still never stored, and no query text is written to logs or usage records. See Privacy and data retention; the Privacy Policy, Terms and DPA are updated.
2026-10-26: fewer refused Google image and search queries
- Fewer
503 upstream_blockedanswers on /v1/images, /v1/search and the other Google result pages. Most of what looked like Google refusing a query was a few of our Google sessions that Google had stopped serving. Requests used to give up after two such sessions; now they try a third, which usually answers in about a second. Sessions Google has stopped serving are checked and replaced in the background. - When Google refuses a web-search page, /v1/search answers
503 upstream_blocked(not charged) about 1.5 seconds sooner: it no longer retries the page in a browser first, which has not rescued such a page since 2026-10-25. Depth requests (numabove 10) that hit a refused page finish sooner too. Retry the query later.
2026-10-25: result parsing fixes
- /v1/videos: every video keeps its own
source,channel,dateandduration. Before, videos hosted outside YouTube could all show the channel and date of the first such video, and a LinkedIn video could be labelled Reddit. - /v1/search:
people_also_askno longer lists the query itself as a question.
2026-10-25: fewer Google image failures
- A Google search with
safe: "active"whose results SafeSearch hides entirely (“Results hidden by SafeSearch”) now returns emptyresultsin about a second, not charged. Before, image searches retried it in a browser and often answered503 upstream_blockedafter up to 10 seconds. - When Google refuses an image query outright, /v1/images answers
503 upstream_blocked(not charged) in about two seconds instead of retrying it in a browser that only met the same refusal. Retry the query later or rephrase it. - A burst of slow Google exits no longer makes every image and search request fail for 30 seconds or more with
503 upstream_error. - When Google’s image page for a query comes back empty, /v1/images returns empty
resultsat once (not charged) instead of retrying it in a browser for 7–10 seconds and answering503 upstream_blocked.
2026-10-24: images paging (API 1.11.0)
Changed
- /v1/images: one page is a block of up to 100 images for 1 credit, and positions continue across pages:
page: 2starts at position 101 (it was numbered from 11, overlapping page 1).num(1–100) now returns only the firstnumimages of the page, for the same credit; before, it was ignored and every page returned up to 100. Leavenumout to keep getting the whole page. See Pagination and depth. - A Google page past the last one on images, news, videos and shopping is recognised as the end of the results: empty
resultsin about a second, not charged. Before, images and news retried it in a browser for up to 15 seconds and sometimes answered503 upstream_blocked. /customsearch/v1withsearchType=image:startcounts images within the first block of 100, as Google’s CSE does (start=11returns images 11–20). Before, it returned the first images of a different block.- The MCP
imagestool takesnum, and@serpkite/ai-sdk0.5.0 addsnumto its images tool.
2026-10-24: cited answers, structured extraction and deep research (API 1.10.0)
New
POST /v1/answer: a short answer to a question, written by Claude Haiku 5.5 from live Google results, with[n]citations incitations.depth: "fast"answers from the results page (1 + 2 credits);depth: "standard"(default) also reads the topnum_sourcespages (default 3, up to 5; 1 + 1 per page + 4 credits).stream: truesends Server-Sent Events (results,delta…,doneorerror);output_schemareturns the answer as JSON inoutput. When the model fails, the model part is refunded and the call returns503 ai_unavailable. See Cited answers.include_answer: trueon /v1/search and /v1/news addsanswer(text,citations) over the response’s results: +2 credits, or +4 withinclude_content. A failed answer is refunded with ameta.warningsentry. Withformat: "markdown"the document leads with## Answer.- /v1/extract:
summary: trueadds a 3–6 sentence summary per page (+4 credits per page);output_schemawith an optionalpromptreturns each page’s data as JSON inresults[].output(+4 credits per page). Schemas of only booleans and enums are answered by OpenAI’s Decisions API, which always returns schema-valid values. A failed AI step is reported insummary_error/output_errorand not charged. See Structured extraction. POST /v1/research: async deep research. Claude plans Google queries, the pages are read and ranked, a decision model checks coverage and drops off-topic sources, follow-up rounds fill gaps, and the result is a Markdown report with[n]citations (plus JSON withoutput_schema).lite30,standard75,deep200 credits, flat, charged only when the report is written. PollGET /v1/research/{id}, cancel withDELETE, or receive the signedresearch.completedwebhook. See Deep research.meta.llm(provider,model,input_tokens,output_tokens) on responses an AI step wrote, andmeta.warningsfor non-fatal problems.- The MCP server has 18 tools: new
answer,researchandresearch_result;searchtakesinclude_answer, andextracttakessummary,output_schemaandprompt. - SDKs: TypeScript, Python and Go 0.7.0 add
answer(andanswerStream/answer_stream/AnswerStream),researchwith a wait helper, and the extract AI options;answerretries only on429so a slow answer is never charged twice.langchain-serpkite0.3.0 addsSerpKiteAnswerandSerpKiteResearch;@serpkite/ai-sdk0.4.0 has 21 tools.
Changed
- Short pages that turn out to be a bot check, a login wall, a soft 404 or an empty app shell are no longer billed or cached on /v1/webpage, /v1/extract, /v1/crawl and
include_content(a decision model checks them). Page monitors no longer report cosmetic changes such as dates, counters or ads. - AI features send the query and page text to Anthropic and OpenAI under their API terms, which exclude training; both are listed as subprocessors. See Privacy and data retention.
2026-10-24: result quality fixes
- /v1/search returns
knowledge_graphagain for entity searches (“eiffel tower”, “marie curie”): title, type, description with its source, facts and website from Google’s current panel layout. A place’s panel no longer hides the organic results under it. answer_boxcovers Google’s entity answers (“capital of australia” → Canberra), currency conversions and dictionary definitions (titleis the word).locationon Google search, news, images, videos and shopping localizes results to that place again (a city name such as “Austin, Texas”); before, results followed the exit’s own region. Aw+uuleyou send localizes the same way.engine: "bing"on /v1/videos returns videos for the query; it sometimes returned short clips matching a single word of it.engine: "yandex"on maps, places and place answers in English withlanguage: "en"(Turkish withtr, Kazakh withkk), and English place names in the query (“coffee in london”) are understood instead of searching around Moscow.- Wikipedia (an
engine: "consensus"source) is blocked less often, so consensus more often has three sources. - /v1/reviews: Google Maps now often shows logged-out visitors a “limited view” with only the first 5 reviews of a place. Such a page ends the list: it has no
next_page_token(before, the token led to a503after about 30 seconds), and it returns about twice as fast. - /v1/reviews answers in about a second instead of 10 to 20: it reads the reviews from the Google Maps place data over plain HTTP, and renders the panel in a browser only when that data has none. It’s the same first 5 reviews in the same order, and now every review has
iso_date, an owner’sresponsecomes in full (it was cut at about 300 characters), anduser.thumbnailis a larger image. numbelow 10 on /v1/reviews returns that many reviews with anext_page_tokenfor the rest, as documented; it used to be rounded up to 10. Still 1 credit per call.- /v1/scholar is blocked less often and answers in about a second more of the time: Google Scholar had started refusing some of the browser versions our requests present.
2026-10-23: Yandex web search
engine: "yandex"on /v1/search now returns Yandex’s organic web results (title,link,domain,displayed_link,snippet, up to 15 a page). Yandex has its own index, the strongest for Russian-language and CIS queries;countrypicks its region. Withengine: "auto"(or a key with fallback on), search falls back to Yandex last. Same credits as Google; failed, blocked and empty requests are free. See Search providers.- Yandex can’t apply a time filter or
safe: "active": a request that names it gets400 invalid_requestwith them (not charged), andautodoesn’t use it for them. The message of that error no longer assumes a time filter.
2026-10-22: depth searches fetch their pages in order (API 1.9.0)
numabove 10 on /v1/search and /v1/news now fetches its pages in order: each page starts once the one before it has answered, or 1.5 seconds after that page started, with at most two pages in flight. Google refuses the same query arriving twice at once, so fetching the pages together returned empty results under load. Anum: 20search takes about a second longer than a single page, andnum: 100roughly 10 seconds. Two pages in a row without results (empty or failed) end the walk, so a query Google is refusing doesn’t spend ten slow attempts. Prices are unchanged: one credit per page that returned results, capped at 7.- Google sometimes answers a page past the first with “did not match any documents” although the next pages have results. Such a page is now fetched once more on another session before it counts as empty, so deep searches return more results.
- When Google blocks a search and the fallback only gets an empty page, the response is now
503 upstream_blocked(not charged) instead of200with emptyresults, which read as “this query has no results”. A query Google says matches nothing is still a200with emptyresults. - A deep page that Google answers with “did not match any documents” but answers fully on a second try now retires the session that served it, so that session doesn’t truncate other searches. A page that is empty on both tries ends the walk without falling back to a slower route.
- A search Google refuses outright (the same refusal on two of our sessions while other searches go through) now moves to the browser fallback after two sessions instead of three, about a second sooner. It is still
503 upstream_blockedand not billed when the browser gets no results either, and the refusal no longer takes healthy sessions out of rotation. - The dashboard counts
200answers without results apart from billed ones: Usage shows how many there were, and the request log can show them alone (status “No results”). The CSV export has anemptycolumn.
2026-10-22: pages that need JavaScript are rendered
- /v1/webpage, /v1/extract, crawls, webpage monitors and
include_contentrender a page in a browser when plain HTTP can’t read it: single-page apps that send an empty shell (the HTTP page is still returned if the render fails), checks that a standard browser passes on its own (Cloudflare’s “Just a moment”, DataDome’s and AWS WAF’s device checks), and pages a site refused to the first exits. A refused page is first retried over residential exits, which pass IP checks the other exits fail, before it is rendered. Pages served as HTML are still fetched over HTTP first, so they are as fast as before. Which sites need a browser is remembered for a few hours, so their next pages skip the steps that can’t read them. - More block pages are recognised (Akamai, CloudFront, Imperva, Sucuri, PerimeterX, Amazon’s and Reddit’s walls), so they are retried through other exits and, failing that, reported as
upstream_blockedand not charged instead of being returned as the page or as the site’s 401/403. A CAPTCHA is never solved: such pages stayupstream_blocked. - A rendered page takes a few seconds more; one request to /v1/webpage can take up to 35 seconds. Public scripts and stylesheets a render downloads are cached and reused by later renders (never cookies, documents or bot-check scripts), so repeat renders of a site skip most of those downloads. The request and response formats are unchanged.
- Webpage errors now describe the page rather than a search upstream:
upstream_blockedsays the site’s bot protection refused every route (we never solve CAPTCHAs),upstream_timeoutthat the page did not load in time. Codes and statuses are unchanged. HTTP 456 (PerimeterX’s block status) counts as a block. So do Avito’s 439, Coupang’s “Access denied” page, Yandex’s “Are you not a robot?” CAPTCHA and Google’s consent wall; Wildberries’ 498 token check and Akamai’s verification interstitial (Amazon search) go to the browser.
2026-10-21: consensus with domain filters, more fallback engines, result fixes (API 1.8.0)
New
engine: "consensus"on /v1/search acceptsinclude_domainsandexclude_domains. Every provider receives the domain operators, the filters apply to the merged rows, and a provider whose rows were all filtered out is not billed. See Search filters.- Consensus replaces a provider that fails or comes back empty with the next index in the route, still with at most three answering providers, so one flaky source no longer leaves a Google-only answer. Billing is unchanged: one page per provider that returned results.
- Bing and DuckDuckGo now answer /v1/images and /v1/videos, and Bing, DuckDuckGo and Yahoo answer /v1/news, as named engines or
engine: "auto"fallbacks after Brave. DuckDuckGo and Yahoo are also web search fallbacks after Bing. See Search providers. - /v1/map with
searchreads up to 8 of the start page’s links one level deeper when the sitemap is thin, sodocs.python.org/3/withsearch: "asyncio"findslibrary/asyncio.html. Still 1 credit.
Fixed
- Google /v1/images:
image_url(and its size) now belongs to the row’s own page. Google lists each tile’s data twice, and rows were paired with the image of the row before. - Google /v1/videos: about one request in three returned empty
results(not billed) when Google served its link-only page layout. Those pages now return their videos. - /v1/extract, /v1/webpage and crawls: a bot-check page served with HTTP 200 (such as “One moment, please… your request is being verified”) is retried through another exit and, if every exit gets it, reported as
upstream_blockedand not charged. It used to be returned, and billed, as the page.
2026-10-21: maps location and place IDs in Markdown
locationnow localizes Google /v1/maps and /v1/places withoutll: Google ignored the encoded location there, so “specialty coffee” withlocation: "Berlin, Germany"could return Munich. The search now asks Google for “qinlocation”; the response still echoes yourqandlocation.llsearches are unchanged. See Localization.format: "markdown"(and the MCPmapstool) lists each place’splace_idandcid(fidwhen neither is known,oidfrom Yandex Maps) and coordinates, so a result can be passed to /v1/place or theplacetool.format: "compact"addsplace_idandoidto maps and places.
2026-10-21: Yandex Maps enabled
- Yandex Maps now answers at api.serpkite.com:
engine: "yandex"on /v1/maps and /v1/places, andoidon /v1/place. Withengine: "auto"(or a key with fallback on), maps and places fall back to Yandex Maps after Google. Same credits as Google; failed, blocked and empty requests are free. See Search providers. - Requests that name Yandex without
languageare answered in Russian (the echo showslanguage: "ru"). Website links drop Yandex’s ad tracking parameters (yclid,utm_*).
2026-10-21: Yandex Maps provider, not enabled yet (API 1.7.0)
New
- The contract and SDKs (0.6.0) know Yandex Maps as a provider for /v1/maps, /v1/places and /v1/place:
engine: "yandex", andoid(a Yandex Maps organisation ID) on /v1/place. Places from Yandex carryoidandyandex_maps_urlin place of the Google IDs. See Search providers. - It is not enabled at api.serpkite.com yet: such requests return
400 invalid_requestand are not charged. Nothing changes for Google requests.
2026-10-21: place details, structured hours, Maps search data (API 1.6.0)
New
POST /v1/place(orGETwith query parameters) returns the full Google Maps listing of one place byplace_id,cidorfid(from a /v1/maps or /v1/places result), withcountry,language,format,fieldsandmax_age.resultsholds the place, or is empty and not charged when no place has that identifier. 1 credit (half on amax_agecache hit and in batches, which acceptendpoint: "place"). The MCP server has a matchingplacetool. See Place details.- New place fields on maps, places and place:
international_phone_number,weekly_hours(per weekday, a list of local{open, close}times in 24-hourHH:MM; closed is[], open 24 hours is00:00–24:00, an interval past midnight hasnext_day: true),country(ISO code, upper case),timezone(IANA),descriptionandgoogle_maps_url./v1/placealso returns up to 10photos(url,width,height,source).opening_hoursis unchanged: English weekday keys, display text inlanguage.
Changed
- /v1/maps and /v1/places read Google Maps search data, so
address,type/types(inlanguage), coordinates, website, phone and hours are filled in every language, Russian included./v1/placesreturns the same results as/v1/maps. ll(@lat,lng,zoomz, zoom 14z by default) searches the map at that point and zoom wherever the request comes from;location(oruule) searches the named place. Without either, Google picks the area from the query or from where the request comes from, so passlocationorllfor local queries such as “coffee”. See Localization.meta.parse_qualityispartialwhen a place lacks a key field (title, coordinates) or a field looks wrong.
2026-10-16: reviews limited to the first 10, most relevant first
- Google Maps now shows logged-out visitors only the first 10 reviews of a place, in its most relevant order: the list stops there, and the sort button asks the visitor to sign in. SerpKite reads logged-out pages only, so /v1/reviews follows:
sortother thanmost_relevant(newest,highest_rating,lowest_rating) returns400 invalid_requestat once instead of failing as503 upstream_blocked, and paging ends at review 10 (numabove 10 returns at most 10; the page that reaches review 10 has nonext_page_token; an older token past review 10 returns an empty page). Neither case is charged. The request schema is unchanged.
2026-10-16: fewer upstream failures under load
- When Google capacity is busy, a request now waits a few seconds for a free session instead of failing at once. Busy capacity is shared fairly between accounts, and realtime calls go before batch jobs and monitor runs, so one account’s burst no longer fails other accounts’ requests. If it still can’t be served, the answer is
503 upstream_blockedwithRetry-After, as before, and isn’t billed. - Batch jobs that hit a temporary upstream failure are retried for you for about five minutes before they are marked
failed. Failed jobs are still refunded.
2026-10-09: OAuth for the MCP server
- The MCP server supports the MCP authorization spec. Clients that can’t send a custom header (Claude and ChatGPT connectors) only need the URL
https://api.serpkite.com/v1/mcp: a401without a credential carriesWWW-Authenticate: Bearer resource_metadata=…, the protected resource metadata nameshttps://app-api.serpkite.comas the authorization server, and the user approves the connection on a SerpKite consent page. Supported: authorization code with PKCE (S256), dynamic client registration, Client ID Metadata Documents, rotating refresh tokens and revocation. - An approved connection runs as an API key named
<client> (OAuth)on the account: calls are billed, limited and logged like that key, and revoking it disconnects the client. OAuth access tokens (skt_oat_…) work on/v1/mcponly. API keys keep working everywhere. - MCP tools now carry
annotations(readOnlyHint,destructiveHint,idempotentHint,openWorldHint) next to theirtitle. Every tool is read-only exceptcrawl, which starts a task.
2026-10-09: bare API key in Authorization
Authorization: skt_live_…without theBearerscheme now authenticates every request, including the MCP server. Some MCP hosts, such as Smithery, forward a configured key as the raw header value.Bearerremains the recommended form; other schemes are still rejected. See Authentication.
2026-10-04: batch idempotency for rejected entries
- Batch creation saves the first
202response under itsIdempotency-Keyeven if all entries are errors and no jobs were queued. Retrying the same key and body replays that response for 24 hours. Use a new key after correcting requests or funding a rejected reservation. See Batch retries.
2026-10-04: monitor run validation
POST /v1/monitors/{id}/runreturns409 invalid_requestfor a paused monitor instead of accepting a run the scheduler cannot execute. Resume it withPATCH {"active": true}, which also schedules an immediate run.- The production edge now allows
PATCHandDELETEon the public API, restoring monitor updates and deletion and crawl cancellation.
2026-10-03: stricter filters, safer crawls and monitors
Changed
include_domains,exclude_domainsandboost_domainsreject entries that could never match (a port, asite:operator, quotes or brackets), convert internationalised domains to punycode and drop duplicates. The filters also apply totop_storiesand the answer box, and to results served from the cache. OnGET /v1/searcha list may also be sent as repeated keys.- The request echo shows
start_dateandend_daterather than thetbsderived from them. /v1/rankreturns400forinclude_domains,exclude_domains,boost_domainsandhighlights./v1/webpagewithformat: compactormarkdownincludeslinksandimage_linkswheninclude_links/include_imagesare set./v1/extract:timeoutdefaults to 50 seconds and is at most 90; a page still loading at the deadline stops (and is free).format: htmlreturns at most 2 MiB of HTML per page. The SDKs retry an extract only on429.- Monitors return
400for search fields they don’t keep (tbs,start_date,include_content…).PATCHandPOST /v1/monitors/{id}/runbind the monitor to the calling key, which its runs are then billed to. POST /v1/crawlreturns503when async workers are off;DELETE /v1/crawl/{id}returns404for an unknown crawl and409for a finished one. A crawl’s pages are capped at 16 MB, and a crawl interrupted by a deploy goes back to the queue.
2026-10-03: async crawls and monitors
New
POST /v1/crawlstarts an async crawl of one site: up to 1,000 pages and 10 link hops from a start URL and the site’s sitemaps, filtered byinclude_paths/exclude_paths, best first withquery, honouringrobots.txtandCrawl-delay. It returns202with a task; pollGET /v1/crawl/{id}(results kept 24 hours), cancel withDELETE /v1/crawl/{id}, or receive the signedcrawl.completedwebhook. Each page read costs 1 credit (0.5 from cache);limitcredits are reserved up front and the rest refunded. See Crawl.- Monitors:
POST /v1/monitorssaves a/v1/searchor/v1/newsrequest (or a/v1/webpageURL) that runs hourly to weekly and reports only what is new, in its run history (GET /v1/monitors/{id}/runs) and to a signedmonitor.resultswebhook when one is set.GET,PATCHandDELETE /v1/monitors/{id}andPOST /v1/monitors/{id}/runmanage them. Each run costs what its request costs; empty runs are free. See Monitors. - MCP tools
crawlandcrawl_result.
2026-10-03: extract up to 20 URLs
New
POST /v1/extractreads 1–20 URLs (HTML or PDF) per call asmarkdown,textorhtml.querywithhighlights(1–10) adds each page’s most relevant passages, ranked with BM25.include_links,include_images,max_tokens,max_age,countryandtimeout(up to 90 seconds, default 50) are supported. Each URL that comes back costs 1 credit (0.5 from cache); failed URLs are listed infailedand cost nothing. The MCP server has a matchingextracttool. See Extract.
2026-10-03: map a site
New
POST /v1/maplists a site’s URLs from the sitemaps named inrobots.txt(or/sitemap.xml) and the start page’s links, cleaned, kept on the host and de-duplicated.searchranks them by relevance;include_paths/exclude_paths(regular expressions on the path),include_subdomains,ignore_query_parametersandsitemap(include,only,skip) narrow the list. 1 credit per call, free when nothing is found. The MCP server has a matchingmaptool. See Map.
2026-10-03: search filters
New
include_domainsandexclude_domainson/v1/search,/v1/news,/v1/imagesand/v1/videos: up to 20 domains, path prefixes or TLDs each, compiled intosite:operators and enforced on the returned rows. They can’t be combined withengine: "consensus".boost_domainson/v1/searchand/v1/news: matching results move to the top.start_dateandend_date(YYYY-MM-DD) on the same four endpoints. They can’t be combined withtimeortbs.published_at(ISO 8601) next todateon organic results, news, top stories and videos.highlights: truewithinclude_contenton/v1/search: up to 3 query-ranked passages per fetched page inresults[].highlightsinstead ofcontent.
None of them costs extra credits. Other endpoints reject them with 400 invalid_request. See Search filters.
2026-10-03: PDFs, links and images on /v1/webpage
New
POST /v1/webpagereads PDFs: the text layer page by page, with<!-- page N -->markers in the Markdown, the page count inmetadata.pagesand the media type inmetadata.content_type. Scanned PDFs without a text layer come back empty and are not billed.include_linksandinclude_imageson/v1/webpageaddlinks(url,text) andimage_linksto the response, at no extra cost. Other endpoints reject them with400 invalid_request.
Changed
- Pages are read up to 8 MiB instead of 2 MiB. A PDF that can’t be read returns
503 upstream_errorand is not billed.
2026-10-03: exit country for webpages
New
countryonPOST /v1/webpage: the page is fetched through an exit in that country (two-letter ISO code, defaultus), for pages that differ by region. The SDKs’webpagemethods and the MCPwebpagetool take it too.
2026-10-03: Lens removed
Removed
- The
POST /v1/lensendpoint (Google Lens visual matches). Google refuses logged-out Lens requests, so the endpoint could not return results. Existing calls now get404. endpoint: lensonPOST /v1/batches, which now returns400 invalid_request.
Every other endpoint is unchanged, as are the credit prices.
2026-10-02: AI Overview and AI Mode removed
Removed
- The
ai_overviewrequest parameter and response field on/v1/search(includingformat=compactandformat=markdownoutput). Sendingai_overviewnow returns400 invalid_request(“AI Overviews are no longer returned; remove it”). - The
POST /v1/ai-modeendpoint. - The
ai_overviewtool on the remote MCP server.
Everything else on /v1/search (organic results, answer box, knowledge graph, People Also Ask, related searches, top stories, local pack and ads) and every other endpoint is unchanged, as are the credit prices.
v1.0.0 (2026-09-29): the v1 API
SerpKite’s own versioned API, published as an OpenAPI 3.1 spec. It replaces the unversioned preview routes.
Breaking changes from the preview
- Paths: every route is under
/v1:/v1/search,/v1/news,/v1/images,/v1/videos,/v1/maps,/v1/places,/v1/reviews,/v1/shopping,/v1/scholar,/v1/patents,/v1/autocomplete,/v1/lens,/v1/ai-mode,/v1/webpage,/v1/rank,/v1/account,/v1/status,/v1/batches.GET /customsearch/v1is unchanged. - Auth:
Authorization: Bearer skt_live_…(or?api_key=on GET). The legacy key header is no longer accepted. - Parameters:
countryandlanguageset the market and interface language. Reviews takeplace_id(orcid/fid),sortandpage_token. The endpoint is chosen by the path, not a body field. - Strict validation: unknown parameters return
400 invalid_request, and the message names the replacement (for exampleunknown parameter "type": use the endpoint path). - Response envelope: every vertical returns
request(the normalised request),results(its primary list: organic rows, images, news, places, reviews, papers, suggestions…), vertical extras andmeta. All keys are snake_case (ai_overview,knowledge_graph,people_also_ask,related_searches,displayed_link,image_url…).fieldspaths follow suit:results.title,results.link,ai_overview. - Batches:
POST /v1/batcheswith{"endpoint", "requests": [1–100 bodies], "webhook_url"}queues one half-price job per request. Realtime endpoints take a single JSON object; array bodies and the batch mode flag are gone. - MCP: the remote server is at
https://api.serpkite.com/v1/mcp, with Bearer auth; tool arguments usecountryandlanguage.
New
engineparameter on/v1/search,/v1/news,/v1/imagesand/v1/videos:google(the default, unchanged),auto, one provider or a list. Opt-in fallback to other search engines when Google is unavailable, labelled inmeta.engineand the newmeta.route, plus a per-key dashboard setting. See Search providers.POST /v1/rank: the best position of a domain for a keyword in the top 10 to 100.GET /v1/status: public per-endpoint success rate and latency over the last hour.- Official SDKs: TypeScript (
npm install serpkite), Python (pip install serpkite, sync and async) and Go (github.com/serpkite/serpkite-go), pluslangchain-serpkiteandserpkite[crewai]. See SDKs.
Unchanged
format(json,compact,markdown),fields,include_content,num: 100depth bundle,max_agecaching, the AI Overview at no extra cost, resolved destination URLs and the credit prices.- Response headers
X-Credits-Used,X-Credits-Remaining,X-Cost-USD,X-Cache,X-Latency-Ms,X-Tokens-Estimate,X-Request-Id. - Failed, empty and blocked requests are refunded automatically.
- Account controls: multiple keys with monthly limits, spend cap, alerts, auto-recharge, teams and a metadata-only request log.
v0.9 (2026-09): preview
The first public preview: JSON search endpoints for Google’s verticals, a webpage-to-Markdown fetcher, the CSE-compatible GET /customsearch/v1, the three output formats, the batch lane with signed webhooks, the remote MCP server, and the dashboard with keys, usage, billing and spend controls.
Planned
These are on the roadmap but not live. Nothing here is a date commitment.
- A local (stdio) MCP package for
npxanduvx.
Incidents
This page covers the API contract only. For outages, degraded performance and incident history, see the status page.
Last updated: 2026-11-13