Skip to content

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

SerpKite
Get API key
Docs menu / API changelog

API changelog

Changes to the SerpKite API contract, newest first. Additive changes ship without notice; anything breaking is announced here in advance.

View as Markdown

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.

  • Live searches again follow held-back result links in the background for up to two minutes. POST /v1/resolve reports pending with retry_after, then resolved when Google releases the destination, or failed when 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.
  • A result link Google holds back past a live request (link_resolved: false) is no longer followed after the response. POST /v1/resolve answers failed for 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/resolve still 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, crawl and research used to be counted twice, so an extract with as many URLs as the key’s rate allows was always refused. initialize, tools/list and notifications no longer count.
  • 429 rate_limited for a full batch queue or the crawl/research task limit now carries Retry-After: 30, and the limits hold exactly under concurrent calls.

2026-11-06: Custom Search parity (API 1.16.0)

  • /customsearch/v1 accepts every Custom Search JSON API parameter. exactTerms, excludeTerms, orTerms, hq, fileType and lowRange/highRange become 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. dateRestrict is applied as written (d3 was widened to a week), lr and cr restrict the documents instead of setting the interface language and country, and safe=high/medium mean active instead of a 400.
  • start can be any index up to result 100 (start + num - 1 <= 100). A window that spans two Google pages, such as start=5 or num=3 at start=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.code is the HTTP status, error.errors[0].reason Google’s reason and error.status the canonical status. SerpKite’s code (formerly error.code) is in error.details[0].reason.
  • A response without results has no items key, as in CSE. totalResults is Google’s estimate when shown, otherwise 100 while 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 flagged link_resolved: false as on /v1/search, with the domain Google showed as displayLink. htmlTitle and htmlSnippet bold the query’s words.
  • /customsearch/v1/siterestrict is served too.
  • Search snippets no longer end with Google’s “Read more” link text, and image results (/v1/images, CSE image.thumbnailLink) now carry thumbnail_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_mode and /v1/brave_ai take location (and uule): local prompts such as “best pizza near me” answer for that city instead of wherever our exit is. country defaults to the location’s country. Brave returns 400 (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_mode and brave_ai take location, so you can track a prompt per city.
  • /v1/research takes location and runs its searches for that place.
  • SDKs 0.10.0 add location and uule to the assistant parameters and location to 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 location and a uule naming a place, instead of being skipped. A search Google refuses with a location can now be answered by Brave for that place (requests without engine, engine: "auto", or a key with fallback on), and engine: "brave" or "yandex" with a location no longer returns 400.
  • An engine that can’t find the place is skipped (a 400 when 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 a uule naming 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.
  • POST /v1/resolve returns the destinations of results that came back with link_resolved: false. SerpKite keeps following those Google redirects after Google’s delay, for up to 2 minutes. A link still pending comes with retry_after seconds 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) and Resolve (Go), along with the link_resolved and unresolved_links fields.

2026-11-05: every result keeps its place (API 1.13.0)

  • Google links results through google.com/goto redirects 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 response parse_quality: "partial". That result is now returned in its place with link_resolved: false. Its link is the Google redirect, and its domain is the host Google displayed for it (empty when Google showed none). Every other result’s link is the destination, as before.
  • meta.unresolved_links counts such results and is absent when there are none. meta.resolved_urls is false while any remain. They no longer make a response partial.
  • 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. In format: "compact" they carry link_resolved: false and domain.
  • 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 country set now has three routes to try in that country instead of one, so far fewer of these requests end with 503 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_reached until 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_blocked or, without engine, 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 with 503 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: true when Google said it hid results very similar to those shown. This explains short results that have no missing_pages.
  • A num above 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_age can’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 num above 10 reports pages it couldn’t retrieve in meta.missing_pages (for example [2]) and sets meta.parse_quality to partial. Before, a page Google refused left a short result marked ok, which looked the same as Google having no more results. Without missing_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_age can’t return it later.
  • parse_quality on a num above 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: 2 and later return a 503 instead 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: page and time work. Bing was answering every page and time window with its first unfiltered page, and those pages were billed.
  • device: "mobile" works on engine: "bing" web search and on engine: "yahoo" web search and news. It used to return an empty result every time.
  • engine: "brave" on /v1/images refuses time, tbs and date ranges (400; engine: "auto" moves to the next engine). Brave’s images ignore them, and the results came back unfiltered.
  • location and uule are 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 applies location.
  • engine: "yahoo" uses Yahoo’s regional site for country where it has one: de, fr, es, it, gb, ca, au, br, mx, in, ar, at, ch. Before, country didn’t change the results.
  • /v1/news with include_domains, exclude_domains or a site: operator in q returns news from Google. It used to return only a few results, or none.
  • /v1/shopping: position no longer repeats between pages, so pages now start at 61, 121 and so on. More results now have image_url (the first cards of a page carry only an inline thumbnail, which is left out), and every result has a link (Google’s product viewer or shopping page when the card doesn’t link to the merchant).
  • /customsearch/v1 returns queries.nextPage for a page with fewer than num results. Only an empty page ends the list.
  • engine: "consensus": position on page: 2 and later continues from the earlier pages instead of restarting at 1.
  • /v1/chatgpt: markdown no longer carries backslash escapes (\\.) or the app’s internal link targets, and pages the answer links to are listed in sources.
  • A fields value with characters that can’t be in a response key returns 400.
  • A finished crawl’s progress shows its final counts.
  • /v1/answer with output_schema fills 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 in failed[].error.code on /v1/extract. These were 503 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: true returns a data: thumbnail in image_url on 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" with device: "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 a domain, which also turned meta.resolved_urls false.
  • engine: "yahoo": language picks a regional site for de, fr, es, it and pt. Other languages are refused (400; engine: "auto" moves on) when country has no regional site, because Yahoo ignores its language filter.
  • /v1/news with include_domains holding a top-level domain (.gov) next to others no longer comes back empty.
  • /v1/news: an include_domains list 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.
  • position continues across pages requested in order: if page: 1 holds 9 results, page: 2 starts at 10 instead of 11. With include_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 503 when several arrive in the same second. Bing mobile pages come back short less often for the same reason.
  • A request with no engine falls 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.route lists parallel attempts in route order.

2026-10-30: wider free-use checks

  • 403 account_restricted now 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/chatgpt 4 credits (was 5), /v1/gemini 3 (was 5), /v1/ai_mode 2 (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_mode and brave_ai tools now describe their inputs in tools/list (prompt, country, language where the assistant takes it, web_search for ChatGPT, track). Before, they listed prompt as 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/gemini answers faster: about 12 seconds at the median, most within 5 to 30 (was about 38, most within 10 to 65).
  • /v1/chatgpt and /v1/gemini: an answer still being written at the 90-second budget is no longer lost. The request fails with 503 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_reached now 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-After with daily_limit_reached, counting down to 00:00 UTC. Before, only the search endpoints did.
  • /v1/chatgpt answers faster: about 17 seconds at the median, most within 10 to 30 (was about 22, most within 15 to 40). The text and markdown no 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 in products.
  • SDKs 0.8.1 (TypeScript, Go) raise daily_limit_reached at once instead of retrying it, as Python already did. Go exports serpkite.CodeDailyLimit, and Error.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 prompt as a logged-out visitor and return its answer (text, markdown with [n](link) citations), the sources it cited or listed (cited flag), the search_queries it ran, the products and places it showed, related_questions and the model it reports: /v1/chatgpt (5 credits; web_search, default true), /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 take prompt (up to 4,000 characters), country, language (not chatgpt), track, include_html, format, fields and max_age. Most answers take 2–65 seconds, depending on the assistant. Failed, refused and empty answers are free; a cache hit with max_age costs 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 in mentions (term, mentioned, cited, sources, products, text_position); with format: "markdown" the answer ends with a ## Mentions section. 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) and track. Every run reports the answer (not only changes) with new_sources, and mentions with track; the monitor.results webhook carries prompt instead of q.
  • /v1/search returns Google’s AI Overview as ai_overview (text, markdown, sources with cited) when the page shows one, at no extra cost.
  • The MCP server has 23 tools: new chatgpt, gemini, copilot, ai_mode and brave_ai.
  • SDKs 0.8.0: TypeScript chatgpt, gemini, copilot, aiMode, braveAi; Python chatgpt, gemini, copilot, ai_mode, brave_ai; Go ChatGPT, Gemini, Copilot, AIMode, BraveAI. They wait at least 120 seconds per attempt and retry only on 429.

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 engine is answered by Brave (then Bing) instead of 503 upstream_blocked or an empty result. meta.engine names 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_blocked with a message that says so and Retry-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 send engine: "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 (num above 10 on /v1/search or /v1/news) will cost 0.5 credits per page that returned results, without the 7-credit bundle cap. A batch num: 100 goes from 3.5 to 5 credits; num: 50 and below are unchanged (num: 70 stays 3.5, num: 80 becomes 4). Realtime prices are unchanged: num: 100 is 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_blocked answers 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 (num above 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, date and duration. 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_ask no 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 empty results in about a second, not charged. Before, image searches retried it in a browser and often answered 503 upstream_blocked after 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 results at once (not charged) instead of retrying it in a browser for 7–10 seconds and answering 503 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: 2 starts at position 101 (it was numbered from 11, overlapping page 1). num (1–100) now returns only the first num images of the page, for the same credit; before, it was ignored and every page returned up to 100. Leave num out 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 results in about a second, not charged. Before, images and news retried it in a browser for up to 15 seconds and sometimes answered 503 upstream_blocked.
  • /customsearch/v1 with searchType=image: start counts images within the first block of 100, as Google’s CSE does (start=11 returns images 11–20). Before, it returned the first images of a different block.
  • The MCP images tool takes num, and @serpkite/ai-sdk 0.5.0 adds num to 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 in citations. depth: "fast" answers from the results page (1 + 2 credits); depth: "standard" (default) also reads the top num_sources pages (default 3, up to 5; 1 + 1 per page + 4 credits). stream: true sends Server-Sent Events (results, delta…, done or error); output_schema returns the answer as JSON in output. When the model fails, the model part is refunded and the call returns 503 ai_unavailable. See Cited answers.
  • include_answer: true on /v1/search and /v1/news adds answer (text, citations) over the response’s results: +2 credits, or +4 with include_content. A failed answer is refunded with a meta.warnings entry. With format: "markdown" the document leads with ## Answer.
  • /v1/extract: summary: true adds a 3–6 sentence summary per page (+4 credits per page); output_schema with an optional prompt returns each page’s data as JSON in results[].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 in summary_error / output_error and 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 with output_schema). lite 30, standard 75, deep 200 credits, flat, charged only when the report is written. Poll GET /v1/research/{id}, cancel with DELETE, or receive the signed research.completed webhook. See Deep research.
  • meta.llm (provider, model, input_tokens, output_tokens) on responses an AI step wrote, and meta.warnings for non-fatal problems.
  • The MCP server has 18 tools: new answer, research and research_result; search takes include_answer, and extract takes summary, output_schema and prompt.
  • SDKs: TypeScript, Python and Go 0.7.0 add answer (and answerStream / answer_stream / AnswerStream), research with a wait helper, and the extract AI options; answer retries only on 429 so a slow answer is never charged twice. langchain-serpkite 0.3.0 adds SerpKiteAnswer and SerpKiteResearch; @serpkite/ai-sdk 0.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_graph again 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_box covers Google’s entity answers (“capital of australia” → Canberra), currency conversions and dictionary definitions (title is the word).
  • location on 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. A w+ uule you 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 with language: "en" (Turkish with tr, Kazakh with kk), 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 a 503 after 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’s response comes in full (it was cut at about 300 characters), and user.thumbnail is a larger image.
  • num below 10 on /v1/reviews returns that many reviews with a next_page_token for 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.
  • 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; country picks its region. With engine: "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 gets 400 invalid_request with them (not charged), and auto doesn’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)

  • num above 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. A num: 20 search takes about a second longer than a single page, and num: 100 roughly 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 of 200 with empty results, which read as “this query has no results”. A query Google says matches nothing is still a 200 with empty results.
  • 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_blocked and not billed when the browser gets no results either, and the refusal no longer takes healthy sessions out of rotation.
  • The dashboard counts 200 answers 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 an empty column.

2026-10-22: pages that need JavaScript are rendered

  • /v1/webpage, /v1/extract, crawls, webpage monitors and include_content render 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_blocked and not charged instead of being returned as the page or as the site’s 401/403. A CAPTCHA is never solved: such pages stay upstream_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_blocked says the site’s bot protection refused every route (we never solve CAPTCHAs), upstream_timeout that 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 accepts include_domains and exclude_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 search reads up to 8 of the start page’s links one level deeper when the sitemap is thin, so docs.python.org/3/ with search: "asyncio" finds library/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_blocked and not charged. It used to be returned, and billed, as the page.

2026-10-21: maps location and place IDs in Markdown

  • location now localizes Google /v1/maps and /v1/places without ll: Google ignored the encoded location there, so “specialty coffee” with location: "Berlin, Germany" could return Munich. The search now asks Google for “q in location”; the response still echoes your q and location. ll searches are unchanged. See Localization.
  • format: "markdown" (and the MCP maps tool) lists each place’s place_id and cid (fid when neither is known, oid from Yandex Maps) and coordinates, so a result can be passed to /v1/place or the place tool. format: "compact" adds place_id and oid to 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, and oid on /v1/place. With engine: "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 language are answered in Russian (the echo shows language: "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", and oid (a Yandex Maps organisation ID) on /v1/place. Places from Yandex carry oid and yandex_maps_url in place of the Google IDs. See Search providers.
  • It is not enabled at api.serpkite.com yet: such requests return 400 invalid_request and 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 (or GET with query parameters) returns the full Google Maps listing of one place by place_id, cid or fid (from a /v1/maps or /v1/places result), with country, language, format, fields and max_age. results holds the place, or is empty and not charged when no place has that identifier. 1 credit (half on a max_age cache hit and in batches, which accept endpoint: "place"). The MCP server has a matching place tool. 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-hour HH:MM; closed is [], open 24 hours is 00:00–24:00, an interval past midnight has next_day: true), country (ISO code, upper case), timezone (IANA), description and google_maps_url. /v1/place also returns up to 10 photos (url, width, height, source). opening_hours is unchanged: English weekday keys, display text in language.

Changed

  • /v1/maps and /v1/places read Google Maps search data, so address, type / types (in language), coordinates, website, phone and hours are filled in every language, Russian included. /v1/places returns 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 (or uule) searches the named place. Without either, Google picks the area from the query or from where the request comes from, so pass location or ll for local queries such as “coffee”. See Localization.
  • meta.parse_quality is partial when 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: sort other than most_relevant (newest, highest_rating, lowest_rating) returns 400 invalid_request at once instead of failing as 503 upstream_blocked, and paging ends at review 10 (num above 10 returns at most 10; the page that reaches review 10 has no next_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_blocked with Retry-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: a 401 without a credential carries WWW-Authenticate: Bearer resource_metadata=…, the protected resource metadata names https://app-api.serpkite.com as 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/mcp only. API keys keep working everywhere.
  • MCP tools now carry annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) next to their title. Every tool is read-only except crawl, which starts a task.

2026-10-09: bare API key in Authorization

  • Authorization: skt_live_… without the Bearer scheme now authenticates every request, including the MCP server. Some MCP hosts, such as Smithery, forward a configured key as the raw header value. Bearer remains the recommended form; other schemes are still rejected. See Authentication.

2026-10-04: batch idempotency for rejected entries

  • Batch creation saves the first 202 response under its Idempotency-Key even 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}/run returns 409 invalid_request for a paused monitor instead of accepting a run the scheduler cannot execute. Resume it with PATCH {"active": true}, which also schedules an immediate run.
  • The production edge now allows PATCH and DELETE on the public API, restoring monitor updates and deletion and crawl cancellation.

2026-10-03: stricter filters, safer crawls and monitors

Changed

  • include_domains, exclude_domains and boost_domains reject entries that could never match (a port, a site: operator, quotes or brackets), convert internationalised domains to punycode and drop duplicates. The filters also apply to top_stories and the answer box, and to results served from the cache. On GET /v1/search a list may also be sent as repeated keys.
  • The request echo shows start_date and end_date rather than the tbs derived from them.
  • /v1/rank returns 400 for include_domains, exclude_domains, boost_domains and highlights.
  • /v1/webpage with format: compact or markdown includes links and image_links when include_links / include_images are set.
  • /v1/extract: timeout defaults to 50 seconds and is at most 90; a page still loading at the deadline stops (and is free). format: html returns at most 2 MiB of HTML per page. The SDKs retry an extract only on 429.
  • Monitors return 400 for search fields they don’t keep (tbs, start_date, include_content…). PATCH and POST /v1/monitors/{id}/run bind the monitor to the calling key, which its runs are then billed to.
  • POST /v1/crawl returns 503 when async workers are off; DELETE /v1/crawl/{id} returns 404 for an unknown crawl and 409 for 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/crawl starts 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 by include_paths / exclude_paths, best first with query, honouring robots.txt and Crawl-delay. It returns 202 with a task; poll GET /v1/crawl/{id} (results kept 24 hours), cancel with DELETE /v1/crawl/{id}, or receive the signed crawl.completed webhook. Each page read costs 1 credit (0.5 from cache); limit credits are reserved up front and the rest refunded. See Crawl.
  • Monitors: POST /v1/monitors saves a /v1/search or /v1/news request (or a /v1/webpage URL) that runs hourly to weekly and reports only what is new, in its run history (GET /v1/monitors/{id}/runs) and to a signed monitor.results webhook when one is set. GET, PATCH and DELETE /v1/monitors/{id} and POST /v1/monitors/{id}/run manage them. Each run costs what its request costs; empty runs are free. See Monitors.
  • MCP tools crawl and crawl_result.

2026-10-03: extract up to 20 URLs

New

  • POST /v1/extract reads 1–20 URLs (HTML or PDF) per call as markdown, text or html. query with highlights (1–10) adds each page’s most relevant passages, ranked with BM25. include_links, include_images, max_tokens, max_age, country and timeout (up to 90 seconds, default 50) are supported. Each URL that comes back costs 1 credit (0.5 from cache); failed URLs are listed in failed and cost nothing. The MCP server has a matching extract tool. See Extract.

2026-10-03: map a site

New

  • POST /v1/map lists a site’s URLs from the sitemaps named in robots.txt (or /sitemap.xml) and the start page’s links, cleaned, kept on the host and de-duplicated. search ranks them by relevance; include_paths / exclude_paths (regular expressions on the path), include_subdomains, ignore_query_parameters and sitemap (include, only, skip) narrow the list. 1 credit per call, free when nothing is found. The MCP server has a matching map tool. See Map.

2026-10-03: search filters

New

  • include_domains and exclude_domains on /v1/search, /v1/news, /v1/images and /v1/videos: up to 20 domains, path prefixes or TLDs each, compiled into site: operators and enforced on the returned rows. They can’t be combined with engine: "consensus".
  • boost_domains on /v1/search and /v1/news: matching results move to the top.
  • start_date and end_date (YYYY-MM-DD) on the same four endpoints. They can’t be combined with time or tbs.
  • published_at (ISO 8601) next to date on organic results, news, top stories and videos.
  • highlights: true with include_content on /v1/search: up to 3 query-ranked passages per fetched page in results[].highlights instead of content.

None of them costs extra credits. Other endpoints reject them with 400 invalid_request. See Search filters.

New

  • POST /v1/webpage reads PDFs: the text layer page by page, with <!-- page N --> markers in the Markdown, the page count in metadata.pages and the media type in metadata.content_type. Scanned PDFs without a text layer come back empty and are not billed.
  • include_links and include_images on /v1/webpage add links (url, text) and image_links to the response, at no extra cost. Other endpoints reject them with 400 invalid_request.

Changed

  • Pages are read up to 8 MiB instead of 2 MiB. A PDF that can’t be read returns 503 upstream_error and is not billed.

2026-10-03: exit country for webpages

New

  • country on POST /v1/webpage: the page is fetched through an exit in that country (two-letter ISO code, default us), for pages that differ by region. The SDKs’ webpage methods and the MCP webpage tool take it too.

2026-10-03: Lens removed

Removed

  • The POST /v1/lens endpoint (Google Lens visual matches). Google refuses logged-out Lens requests, so the endpoint could not return results. Existing calls now get 404.
  • endpoint: lens on POST /v1/batches, which now returns 400 invalid_request.

Every other endpoint is unchanged, as are the credit prices.

2026-10-02: AI Overview and AI Mode removed

Removed

  • The ai_overview request parameter and response field on /v1/search (including format=compact and format=markdown output). Sending ai_overview now returns 400 invalid_request (“AI Overviews are no longer returned; remove it”).
  • The POST /v1/ai-mode endpoint.
  • The ai_overview tool 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/v1 is unchanged.
  • Auth: Authorization: Bearer skt_live_… (or ?api_key= on GET). The legacy key header is no longer accepted.
  • Parameters: country and language set the market and interface language. Reviews take place_id (or cid/fid), sort and page_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 example unknown 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 and meta. All keys are snake_case (ai_overview, knowledge_graph, people_also_ask, related_searches, displayed_link, image_url…). fields paths follow suit: results.title,results.link,ai_overview.
  • Batches: POST /v1/batches with {"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 use country and language.

New

  • engine parameter on /v1/search, /v1/news, /v1/images and /v1/videos: google (the default, unchanged), auto, one provider or a list. Opt-in fallback to other search engines when Google is unavailable, labelled in meta.engine and the new meta.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), plus langchain-serpkite and serpkite[crewai]. See SDKs.

Unchanged

  • format (json, compact, markdown), fields, include_content, num: 100 depth bundle, max_age caching, 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 npx and uvx.

Incidents

This page covers the API contract only. For outages, degraded performance and incident history, see the status page.

Last updated: 2026-11-13