Skip to content
Serpwire
TR

Overview

API reference

Serpwire answers Google searches over HTTP. Every type is a POST to one path with a JSON body, and every response is JSON in serper.dev's shape plus two keys: searchParameters (the normalized request) and credits (what the call cost).

Base URLhttps://serp-api.ozymoz.com
curl -X POST 'https://serp-api.ozymoz.com/search' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "q": "best espresso machine",
    "gl": "us",
    "hl": "en"
  }'

Authentication#

Send your API key in the X-API-KEY header — the same header serper uses. Authorization: Bearer YOUR_API_KEY is accepted too. Create and delete keys in the dashboard; a key is shown once, when it is created.

headers
X-API-KEY: YOUR_API_KEY
Content-Type: application/json

Errors#

Errors share one shape and a stable code. The message is human text; branch on the code.

402 Payment Required
{
  "error": {
    "code": "insufficient_credits",
    "message": "This request costs 3 credits; the balance is 1."
  }
}
HTTPCodeWhen
400invalid_requestValidation failed — the message names the field.
401invalid_api_keyMissing or unknown API key.
401unauthorizedMissing or expired dashboard session.
402insufficient_creditsBalance is lower than the cost of the request (or batch).
403forbiddenAdmin-only route.
409email_takenSign-up with an email that already has an account.
429rate_limitedToo many requests for this key — default 10 per second.
500upstream_failedGoogle answered something unusable after retries. Not billed.
503no_capacityNo healthy Google session in time. Not billed — retry shortly.

Batch requests#

Send an array of up to 100 request objects instead of one. The response is an array in the same order. Each item is billed separately, and the whole batch is checked against your balance up front (402 if it is short). A failed item sits in its place as an error object with credits 0 and the response is still 200; only when every item fails does the response take the first item's error status.

curl -X POST 'https://serp-api.ozymoz.com/search' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "q": "apple",
      "gl": "us"
    },
    {
      "q": "elma",
      "gl": "tr",
      "hl": "tr"
    }
  ]'
response.json
[
  {
    "searchParameters": {
      "q": "apple",
      "gl": "us",
      "type": "search",
      "engine": "google"
    },
    "organic": [
      "…"
    ],
    "credits": 1
  },
  {
    "error": {
      "code": "upstream_failed",
      "message": "Google answered something unusable."
    },
    "credits": 0
  }
]

Rate limits#

Each API key may send up to 10 requests per second by default. Over that you get 429 rate_limited — back off briefly and retry. Ask us if you need a higher limit.

Credits & billing#

Credits are deducted only for a successful (2xx) answer; a failed call costs 0. Each response reports its cost in credits.

Endpoints