# SERP API reference: GET /search and GET /credits

> SerpCrypto SERP API reference: GET /search parameters, engines, defaults, response blocks, error codes and GET /credits, with curl, Python and Node.js.

- URL: https://serpcrypto.com/docs/search/
- Last updated: 2026-10-22
- Publisher: SerpCrypto (https://serpcrypto.com)

Every parameter, default and error code of the SerpCrypto API, version 1. Base URL: `https://serpcrypto.com/api/v1`. All requests use HTTPS; all answers are JSON in UTF-8.

**Quick answer — What parameters does the SerpCrypto search endpoint take?**

`GET https://serpcrypto.com/api/v1/search` takes one required parameter, `q`, and nine optional ones: `engine`, `gl`, `hl`, `location`, `google_domain`, `device`, `page`, `safe` and `period`. **SerpCrypto** returns JSON and charges 1 credit per successful search on all 6 engines; errors are free. Packs start at $7.50 for 10,000 searches, paid in crypto with no KYC.

## How do I authenticate?

Send your key in one of two ways. The recommended way is the header `Authorization: Bearer YOUR_KEY`. The other is the query parameter `api_key=YOUR_KEY`, handy for a quick test in a browser tab.

A missing, wrong or revoked key gets `401 invalid_api_key` and costs nothing. API keys you can create and revoke at any time from your dashboard, so you can give each script or server its own key and revoke one without touching the others.

## Run a search

`GET /api/v1/search`

Runs one search on the chosen engine and returns the results page as JSON. A successful search uses 1 credit, whatever the engine; an error uses none. Parameters go in the query string, URL-encoded. The example asks Google for coffee roasters in Austin, Texas; IDs, counts and results are illustrative.

Authentication: API key in the `Authorization: Bearer API_KEY` header.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | Yes | The search query, as a person would type it. Search operators such as quotes or `site:` are part of the query. |
| `engine` | query | string | No | `google` (default), `google_news`, `google_images`, `google_maps`, `google_shopping` or `bing`. |
| `gl` | query | string | No | Country of the results: ISO 3166-1 alpha-2 code in lower case, such as `us`, `de` or `br`. Default `us`. |
| `hl` | query | string | No | Interface language, such as `en`, `de` or `pt-BR`. Default `en`. |
| `location` | query | string | No | City-level place, written `City, Region, Country`, such as `Austin, Texas, United States`. See [locations](https://serpcrypto.com/docs/locations/). |
| `google_domain` | query | string | No | Google domain to search, such as `google.de`. Default: the domain of the `gl` country. Ignored when `engine=bing`. |
| `device` | query | string | No | `desktop` (default) or `mobile`. |
| `page` | query | integer | No | Results page from 1 (default) to 10. Each page is a separate search and uses 1 credit. |
| `safe` | query | string | No | `active` filters explicit results; `off` (default) does not. |
| `period` | query | string | No | Only results from the last hour (`h`), day (`d`), week (`w`), month (`m`) or year (`y`). |
| `api_key` | query | string | No | Your key, if you do not send the `Authorization` header. |

**Response** `200`

```json
{
  "search_metadata": {
    "id": "srch_7f3a9c2e41b8",
    "status": "success",
    "engine": "google",
    "created_at": "2026-10-22T09:14:05Z",
    "credits_used": 1
  },
  "search_parameters": {
    "engine": "google",
    "q": "coffee roasters",
    "gl": "us",
    "hl": "en",
    "location": "Austin, Texas, United States",
    "google_domain": "google.com",
    "device": "desktop",
    "page": 1
  },
  "search_information": {
    "total_results": 18600000,
    "query_displayed": "coffee roasters"
  },
  "local_results": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "address": "123 Example St, Austin, TX",
      "rating": 4.7,
      "reviews": 312,
      "type": "Coffee roasters"
    }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "The 12 best coffee roasters in Austin",
      "link": "https://www.example.com/austin/coffee-roasters",
      "displayed_link": "www.example.com › austin › coffee",
      "snippet": "From light Nordic roasts to dark espresso blends, these local roasters…",
      "date": "Sep 30, 2026"
    },
    {
      "position": 2,
      "title": "Example Roasting Co. | Fresh beans, roasted in Austin",
      "link": "https://www.example.org/",
      "displayed_link": "www.example.org",
      "snippet": "Small-batch coffee roasted every weekday and shipped the same day…"
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the oldest coffee roaster in Austin?",
      "snippet": "…",
      "title": "Austin coffee history",
      "link": "https://www.example.net/austin-coffee-history"
    }
  ],
  "related_searches": [
    {
      "query": "coffee roasters near me"
    },
    {
      "query": "coffee roasters austin wholesale"
    }
  ],
  "pagination": {
    "current": 1,
    "next_page": 2
  }
}
```

*curl*

```bash
curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=coffee roasters" \
  --data-urlencode "location=Austin, Texas, United States" \
  -d gl=us -d hl=en -d device=desktop
```

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/search",
    params={
        "q": "coffee roasters",
        "location": "Austin, Texas, United States",
        "gl": "us",
        "hl": "en",
    },
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json()["organic_results"][0]["link"])
```

*Node.js*

```javascript
const params = new URLSearchParams({
  q: "coffee roasters",
  location: "Austin, Texas, United States",
  gl: "us",
  hl: "en",
});
const res = await fetch("https://serpcrypto.com/api/v1/search?" + params, {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const data = await res.json();
console.log(data.organic_results?.[0]?.link);
```

## Which engine values exist, and what does each return?

The frame (`search_metadata`, `search_parameters`, `search_information`) is the same on every engine. A block appears only when the page shows it.

| `engine` | Source | Main blocks in the answer |
| --- | --- | --- |
| `google` | Google Search | `ai_overview`, `organic_results`, `ads`, `people_also_ask`, `local_results`, `knowledge_graph`, `top_stories`, `inline_videos`, `shopping_results`, `related_searches`, `pagination` |
| `google_news` | Google News | `news_results`: title, link, source, date, snippet, thumbnail |
| `google_images` | Google Images | `images_results`: original URL and size, thumbnail, source page |
| `google_maps` | Google Maps | `local_results`: name, address, phone, website, rating, reviews, category, hours, coordinates |
| `google_shopping` | Google Shopping | `shopping_results`: title, price, extracted price, currency, merchant, delivery, rating |
| `bing` | Bing | `organic_results`, `related_searches` |

## Read your credits

`GET /api/v1/credits`

Returns the credits left on your account, the credits used since midnight UTC and the number of searches your account may run at the same time. This call is free. Values below are examples.

Authentication: API key in the `Authorization: Bearer API_KEY` header.

**Response** `200`

```json
{
  "credits_remaining": 84210,
  "credits_used_today": 1290,
  "concurrency_limit": 10
}
```

*curl*

```bash
curl -s "https://serpcrypto.com/api/v1/credits" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY"
```

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/credits",
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["credits_remaining"])
```

*Node.js*

```javascript
const res = await fetch("https://serpcrypto.com/api/v1/credits", {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const { credits_remaining } = await res.json();
console.log(credits_remaining);
```

## Which errors can the API return?

Every error has the body `{"error": {"code": "…", "message": "…"}}`. The [errors page](https://serpcrypto.com/docs/errors/) explains each one and shows retry code.

| HTTP | `code` | When it happens | Charged |
| --- | --- | --- | --- |
| 400 | `invalid_parameter` | A required parameter is missing or a value is outside the allowed list | No |
| 401 | `invalid_api_key` | The key is missing, wrong or revoked | No |
| 402 | `insufficient_credits` | Your account has no credits left | No |
| 429 | `concurrency_limit` | Too many searches are running at the same time on your account | No |
| 502 | `search_failed` | The engine or the collection failed for this request; retry it | No |
| 504 | `search_timeout` | No answer in time; retry it | No |

## What is charged, exactly?

- **One successful search = one credit**, on every engine, including Google Maps and Google Shopping.
- **Each results page is one search.** About 10 organic results per page, as Google has served since it stopped honouring num=100 in September 2025; each extra page is one more credit.
- **Errors are free:** every answer with an HTTP status other than 200 uses no credit.
- **Reading your credits is free.**

Prepaid search credits never expire: unused searches stay on your account until you use them. Packs run from $7.50 for 10,000 searches to $0.30/1K searches on the largest one; see [pricing](https://serpcrypto.com/pricing/).

## How should I encode the query?

Send `q` URL-encoded, like any query-string value: a space becomes `%20` or `+`, and accented letters are encoded as UTF-8. curl does this with `--data-urlencode`, Python `requests` and `httpx` do it with `params=`, and Node.js does it with `URLSearchParams`.

Write the query exactly as a person would type it in the search box. Quotes, a minus sign or `site:` stay inside `q`; the engine decides how to apply them, as it would for a visitor.

## Is the API versioned?

Yes. The version is part of the path: `/api/v1/`. New fields or blocks can appear in version 1 answers, so your code should ignore keys it does not know. Removing or renaming a field would come with a new version in the path, not as a change to `v1`.

## API reference questions

### Can I send a POST request with a JSON body?

Not in version 1: both endpoints take GET requests with parameters in the query string. This keeps every call easy to reproduce with curl or a browser, and easy to log without the body.

### How many results does one search return?

About 10 organic results per page, as Google has served since it stopped honouring num=100 in September 2025; each extra page is one more credit. To collect 30 results, request `page=1`, `page=2` and `page=3`: three searches, three credits.

### What happens when my credits run out?

The next search returns `402 insufficient_credits` and uses nothing. Buy another pack from your balance on the [pricing page](https://serpcrypto.com/pricing/); your key keeps working and searches resume at once.

### Can I use the same key from several servers?

Yes. A key is not tied to an IP address. What is limited is the number of searches running at the same time on the account: `concurrency_limit` in `GET /credits` gives the figure.

---

SerpCrypto: SerpCrypto is a SERP API for developers and AI agents that returns Google and Bing results as JSON, paid in crypto with no ID upload. Prepaid search credits from $0.30/1K searches never expire. No KYC — no ID, no selfie, no documents. Pay in crypto.