Skip to content
SpideyData
Get API key

SERP guide · four-step manual

How to Use the SERP API: Auth, Idempotency, Sync vs Tasks

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

Four numbered steps, one HTTP exchange each, across the 12 SERP operations: authenticate, make writes safe to retry, call a sync endpoint, then queue a task and poll it.

Get API keySee SERP tasks →

Baidu and Ecosia endpoints opening soon.

Published · Updated

Step 1 · Authenticate

Create an API key in the console and send it on every request as Authorization: Bearer <key>. A missing or invalid key returns 401.

Step 2 · The Idempotency-Key experiment

Send the same request twice with the same key and watch what gets charged.

  1. Pick a key of 1–128 characters that names the logical request, for example demo-001.
  2. Send POST /v1/serp/bing/organic with that key. The search completes and is charged once.
  3. Send the identical request with the same key, as a retry would. It is a replay: no second charge.
  4. Change the body but keep the key: the API answers 409, because a key may only be reused for the same request.

Step 3 and 4 · Sync call, then a task

curl: sync first, then async
# Step 3 · sync, Bing (this body has no hl)
curl -X POST https://kieapi.com/v1/serp/bing/organic \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: demo-001" \
  -d '{"q":"ergonomic chair","country":"US"}'

# Step 4 · async, Google only
curl -X POST https://kieapi.com/v1/serp/google/news/tasks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"q":"ai regulation","hl":"en"}'
# ← 202 {"job":{"id":"<task_id>","kind":"google_news","status":"queued","attempt_count":0,"max_attempts":3}}
curl https://kieapi.com/v1/serp/tasks/<task_id> -H "Authorization: Bearer $KEY"
# ← 200 {"job":{"status":"completed","result":{"vertical":"news","news":[…],"news_count":…}}}
# ← 404 not_found if the id is unknown

Polling GET /v1/serp/tasks/{task_id} is free. Results arrive by polling only; there are no webhooks.

Error decoder

400

When it appears: Body fails validation, for example hl sent to a Bing body

What to do: Fix the body; extra fields are rejected

401

When it appears: Missing or invalid Bearer key

What to do: Send a valid key

402

When it appears: Not enough Credits for the search

What to do: Add Credits, retry with the same Idempotency-Key

403

When it appears: The key is not allowed to use this endpoint

What to do: Check the key's team and permissions in the console

409

When it appears: Idempotency-Key reused for a different request, or billing needs reconciliation

What to do: Use a new key for a new request

429

When it appears: Temporary rate limit

What to do: Wait for Retry-After, then retry

502

When it appears: The upstream fetch failed

What to do: Retry with the same key; failed searches are not charged

503

When it appears: The endpoint is not open yet or a required service is unavailable

What to do: Retry later; 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.

Frequently asked questions

Does the Bing body accept hl?

No. SerpOrganicRequest has only q and country, and extra fields are rejected with 400.

How long can an Idempotency-Key be?

1 to 128 characters.

What does 429 mean?

RateLimited: a temporary, platform-wide rate limit. Wait for the Retry-After header; this page does not quote thresholds.

Which engines can I use today?

Google, Bing, Yahoo and DuckDuckGo are callable today with a Bearer API key. Baidu and Ecosia endpoints opening soon: until they open, requests return 503 service_unavailable and are not charged. The SERP API as a whole is not GA.

Make your first call

One Bearer key, an Idempotency-Key per logical request, and sync or task endpoints as the job needs.

Get API keySERP API overviewRead the SERP docs

Baidu and Ecosia endpoints opening soon.