Documentation

Choose a search API below. Each page has its own examples and field reference; authentication and account endpoints are covered here.

Base URL: https://api.serqo.io

Search APIs

Google

Bing

Before you start

Create an API key in the console, then set SERP_API_KEY to your key.

bash

export SERP_API_KEY='YOUR_API_KEY'

Authentication

Pass your API key as a bearer token or via the x-api-key header. Keys are created in the console and shown only once.

http

Authorization: Bearer YOUR_API_KEY
# or
x-api-key: YOUR_API_KEY

Do not put keys in URL query strings. Keep them server-side.

Endpoints

Method	Path	Description
POST	/v1/search	Run a search. Set `type` to choose the search type.
GET	/v1/search	Same as POST, with parameters in the query string.
GET	/v1/engines	List engines and their supported search types.
GET	/v1/me	The account and key making the request.
GET	/v1/health	API health check. No API key required; does not test search engines.
GET	/healthz	Server health only; does not test search engines. No API key required.

Supported search types

Choose a search type with type. Omit it for a web search. Google supports all nine types below; Bing supports web, news, images, videos and maps. A dash means the engine does not support that type.

Call GET /v1/engines with your API key to check available engines and their verticals before sending a search.

Search type	Request value	Google	Bing
Web	web	✓	✓
News	news	✓	✓
Images	images	✓	✓
Videos	videos	✓	✓
Maps	maps	✓	✓
Shopping	shopping	✓	—
Forums	forums	✓	—
Books	books	✓	—
Patents	patents	✓	—

`GET /v1/engines`

List available search engines and the search types each supports. Use the engine id and a supported vertical in your search request.

API key required. No query parameters or request body needed.

Request example

bash

curl https://api.serqo.io/v1/engines \
  -H "Authorization: Bearer $SERP_API_KEY"

200 response

JSON

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "engines": [
      {
        "id": "google",
        "displayName": "Google",
        "verticals": [
          "web",
          "images",
          "videos",
          "news",
          "shopping",
          "forums",
          "books",
          "maps",
          "patents"
        ],
        "pagination": "start"
      },
      {
        "id": "bing",
        "displayName": "Bing",
        "verticals": [
          "web",
          "news",
          "images",
          "videos",
          "maps"
        ],
        "pagination": "start"
      }
    ]
  }
}

Response path	Type	Contents
data.engines	array	Available engines.
data.engines[].id	string	Value to pass as engine.
data.engines[].displayName	string	Engine name for display.
data.engines[].verticals	string[]	Allowed type values for this engine.
data.engines[].pagination	string	Pagination method, currently start.

Abbreviated example. Engine entries also include requiresSession and captchaSolve; these describe engine behavior and are not search request parameters. This request does not consume search credits. Invalid keys return 401; engine-list failures can return 5xx.

`GET /v1/me`

Check which account and API key are making the request. The response does not include the full API key or credit balance.

API key required. No query parameters or request body needed.

Request example

bash

curl https://api.serqo.io/v1/me \
  -H "Authorization: Bearer $SERP_API_KEY"

200 response

JSON

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "account": {
      "id": "account_example",
      "email": "developer@example.com",
      "role": "user"
    },
    "key": {
      "id": "key_example",
      "prefix": "sk_example"
    }
  }
}

Response path	Type	Contents
data.account.id	string	Account ID.
data.account.email	string	Account email.
data.account.role	string	Account role: user or admin.
data.key.id	string	ID of the API key used.
data.key.prefix	string	Key prefix for identifying the key.

Example account values are illustrative. This request does not consume search credits. An invalid, revoked or expired key returns 401 UNAUTHORIZED.

`GET /v1/health`

Check whether the API service responds. This does not test search engines, account access or available credits.

No API key, query parameters or request body needed.

Request example

bash

curl https://api.serqo.io/v1/health

200 response

JSON

{
  "success": true,
  "data": {
    "status": "ok"
  }
}

data.status is ok when the service responds. This endpoint does not use the usual requestId response body. It does not consume search credits.

`GET /healthz`

Check server status and process uptime. Use /v1/health for a simple API health check.

No API key, query parameters or request body needed.

Request example

bash

curl https://api.serqo.io/healthz

200 response

JSON

{
  "status": "ok",
  "uptimeMs": 12345
}

Abbreviated response; uptimeMs is an illustrative number of milliseconds. The response also includes env and serp.integration. This endpoint returns a plain status object without success or data, does not test search engines, and does not consume search credits.

Errors

Check the error reason and retry guidance when a search fails. Provide the request ID when troubleshooting.

JSON

{
  "success": false,
  "requestId": "req_01H…",
  "error": {
    "code": "INVALID_PARAM",
    "message": "Invalid search parameter",
    "retryable": false
  }
}

Common errors

400 · BAD_REQUEST: Check that the request is valid JSON and includes a non-empty query.
400 · UNSUPPORTED_VERTICAL: Choose a search type supported by the selected engine.
400 · GEO_CONFLICT: The requested region conflicts with the search connection. Check the country code and provide the request ID if the error persists.
401 · UNAUTHORIZED: Provide an active, unexpired API key for an active account. Invalid, revoked and expired keys return UNAUTHORIZED.
402 · INSUFFICIENT_CREDITS: Your available balance cannot cover the request.
422 · INVALID_PARAM: Check the parameter name, type and allowed values.
429 · QUOTA_EXCEEDED / QUEUE_FULL: For QUOTA_EXCEEDED, wait for retryAfterMs before retrying. QUEUE_FULL also returns 429; follow its retry guidance.
502/503/504: Upstream failures are not charged. Follow the response’s retry guidance.
500 · INTERNAL_ERROR: Keep the request ID for troubleshooting.

Check the HTTP status before reading JSON. Network failures and responses from a proxy may not contain the API error body. Preserve the request ID when one is available.

Retry only when error.retryable is true. If error.retryAfterMs is present, wait at least that many milliseconds. To safely retry after a lost response, send the same Idempotency-Key with the same parameters; the original successful response is replayed without another search or charge for 24 hours. Without that header, a retry is a new request and uses the applicable credit rate.

The request ID is available in the response body and the x-request-id response header.

Rate limits and credits

Rate limits

Each API key uses the account’s per-minute limit. Playground sessions are limited separately. A 429 response includes the wait time in milliseconds; wait before retrying.

Credit usage

Cost depends on search type, engine, country and cache status. Failed searches and timeouts are not charged. View your available balance and credit history in Plan and credits.

Cache hits are free at the default rate. Before a search starts, your available balance must cover the full request cost, even if the result later comes from cache.