Skip to content
SpideyData
Get API key

API contract

SERP Scraper API

A scraper with an API contract.

Google, Bing, Yahoo and DuckDuckGo: live · Baidu and Ecosia: opening soon · not GA

If you are judging how painless an integration will be, read the contract first: Bearer auth, an optional Idempotency-Key, and a fixed set of documented HTTP statuses on every SERP endpoint.

Get API keyPreview error contract

Baidu and Ecosia endpoints opening soon.

Node · Yahoo organic with an idempotency key
const res = await fetch("https://kieapi.com/v1/serp/yahoo/organic", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", "Idempotency-Key": "job-42-q7" },
  body: JSON.stringify({ q: "best hiking boots", country: "US" })
});
if (res.status === 402) throw new Error("top up Credits");

HTTP status table

Every sync SERP endpoint documents the same responses.

400

Error: ValidationError

What to do: Fix the body: q is 1–512 characters and unknown fields are rejected.

401

Error: AuthenticationRequired

What to do: Send Authorization: Bearer <api_key>.

402

Error: InsufficientCredits

What to do: Top up Credits, then retry.

403

Error: PermissionDenied

What to do: The key is not allowed to call this endpoint.

409

Error: BillingConflict

What to do: The same Idempotency-Key collided in billing; do not reuse keys across different requests.

429

Error: RateLimited

What to do: Back off and retry later.

502

Error: FetchFailed

What to do: Upstream fetch failed; failed searches are not charged.

503

Error: ServiceUnavailable

What to do: The endpoint is not enabled ("SERP API is not enabled.") or no session is available; nothing is billed.

Idempotency walkthrough

  1. Generate a key per logical search, 1–128 characters, for example job-42-q7.
  2. Send it in the Idempotency-Key header with the first request.
  3. If the connection drops, replay the identical request with the same key.
  4. The search is billed once; a conflicting reuse returns 409 BillingConflict.

Per-run platforms vs per-request APIs

Actor-style platforms bill a run, which may contain many queries. This API charges per successful search at a display rate of 2 Credits; failed searches are not charged.

Launch status for this page

Check engine availability before choosing an endpoint. Google also supports News, Images and asynchronous tasks.

  • GoogleLiveGoogle is callable today with a Bearer API key.
  • BingLiveBing is callable today with a Bearer API key.
  • YahooLiveYahoo is callable today with a Bearer API key.
  • DuckDuckGoLiveDuckDuckGo is callable today with a Bearer API key.
  • BaiduOpening soonBaidu endpoints opening soon: until they open, requests return 503 service_unavailable and are not charged.
  • EcosiaOpening soonEcosia endpoints opening soon: until they open, requests return 503 service_unavailable and are not charged.

SERP searches are charged per successful search at a display rate of 2 Credits per search; failed searches are not charged. Polling task status is free. The current rate is on Pricing.

What this is not

  • No published rate-limit thresholds; 429 means back off.
  • No uptime or latency SLA.
  • No webhook or callback.
  • Structured JSON only.

Frequently asked questions

What does 409 mean?

BillingConflict: billing for the same Idempotency-Key conflicted.

Is Idempotency-Key required?

No, it is optional. When sent it must be 1–128 characters.

What is returned when SERP is disabled?

503 service_unavailable with the message "SERP API is not enabled."

Do failed fetches cost Credits?

No. Failed searches are not charged; you are charged per successful search only.

Integrate against a fixed contract

Get an API key and handle eight documented statuses instead of guessing.

Get API keySERP API overviewRead the SERP docs

Baidu and Ecosia endpoints opening soon.