---
name: serpbase
description: Live Google search results and structured data from search engines, social media, e-commerce and maps through the SerpBase API (43 endpoints, JSON). Use when a task needs current web search results, SERP features, Google Maps places, YouTube/TikTok/Reddit data or product pages, and an API key is available.
---

# SerpBase API skill

Use this skill when you need live search results or structured data from the web and a SerpBase API key is available in the environment (usually `SERPBASE_API_KEY`). Do not use it for general knowledge you already have, and do not retry blindly: every successful request costs credits.

## Authentication

- Base URL: `https://api.serpbase.dev`
- Send the key in the `X-API-Key` header. Never put it in a URL or log it.
- Every endpoint is `POST` with a JSON body (a few also accept `GET` with query parameters). Set `Content-Type: application/json`.

## The one rule that matters: read `status`, not the HTTP code

Every endpoint answers HTTP 200 with a JSON envelope. Success is `"status": 0`. Anything else is a failure and `error` says why. `request_id` identifies the request for support; `credits_charged` is what the request actually cost (0 on failure).

```json
{ "status": 0, "request_id": "r-…", "elapsed_ms": 1240, "credits_charged": 1, "organic": [ … ] }
```

| status | Name | Meaning | Charged? | What to do |
| --- | --- | --- | --- | --- |
| 0 | SUCCESS | Request completed successfully. Inspect product-specific outcome fields; no_results alone is not proof of HTTP 404. | yes | Use the result. An empty result list with status 0 is a real "no results". |
| 1000 | INVALID_REQUEST | Missing or invalid body or parameters. | no | Fix the request; `error` names the problem. |
| 1001 | UNAUTHORIZED | Missing, invalid, or revoked API key. | no | Stop and ask for a valid API key. |
| 1004 | NOT_FOUND | Resource not found on gateway routing or catalog. | no | The endpoint path is wrong; check the table below. |
| 1020 | INSUFFICIENT_CREDITS | Account balance is not enough. | no | Stop; the account needs credits at https://serpbase.dev/billing. |
| 1029 | RATE_LIMITED | QPS or concurrency limit exceeded. | no | Wait the seconds in the `Retry-After` header, then resend. |
| 1500 | INTERNAL_ERROR | Unexpected internal server error. | no | Retry once after 2 s; if it repeats, report the `request_id`. |
| 1502 | UPSTREAM_FAILED | Worker returned an upstream fetch or parse error. | no | Retry once after 2 s if `X-SerpBase-Retryable` is `true`; otherwise change the query. |
| 1503 | SERVICE_UNAVAILABLE | No worker session is available. | no | Retry after 1–2 s, up to 3 times. |
| 1504 | UPSTREAM_TIMEOUT | Gateway timed out waiting for a worker result. | no | Retry once with a larger `timeout`, or accept that the source was slow. |

Set a client timeout of at least 60 s for Google search; a result can take 2–10 s because it comes from a real browser session.

## A first request

```bash
curl -X POST 'https://api.serpbase.dev/google/search' \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $SERPBASE_API_KEY" \
  --max-time 60 \
  -d '{"q": "best coffee grinder 2026", "gl": "us", "hl": "en", "device": "mobile"}'
```

Common Google search parameters: `q` (required), `gl` (country, e.g. `us`), `hl` (language, e.g. `en`), `device` (`mobile` or `desktop`), `location` (a city or region name, mobile only), `page` (1-based; each page is one request). The answer carries the result blocks the page had: `organic`, `ai_overview`, `people_also_ask`, `local_results`, `top_stories`, `knowledge_graph`, `related_searches` and others; absent blocks were not on the page. Cite `organic[].link` when reporting sources. Google wraps some links in redirectors; `POST /google/resolve` turns them into real URLs for free.

## Spending credits wisely

- Prices are per request and fixed per endpoint (table below); a Google search is 1 credit. Failed requests are not charged.
- Ask for one page at a time and only the pages you need. Do not loop over pages to "get everything".
- Cache results you may reuse in the same task; identical queries cost the same each time.
- Prefer the specific endpoint (news, images, maps, shopping) over filtering a web search.

## Endpoints (43 available)

### Search engines

| Endpoint | Name | Credits | What it returns |
| --- | --- | --- | --- |
| `POST /google/search` | Google Web Search | 1 | Search Google web results with q, language hl, country gl and a supported device. |
| `POST /google/image/search` | Google Images Search | 1 | Search Google Images by query for image results and source links. |
| `POST /google/news/search` | Google News Search | 1 | Google News API: search Google News by keyword, country and language, and get each story's title, link, source, publish time, snippet and image as JSON.. |
| `POST /google/videos/search` | Google Videos Search | 1 | Search Google video results by query. |
| `POST /google/autocomplete` | Google Search Autocomplete | 1 | Retrieve Google search suggestions for a query prefix. |
| `POST /google/shopping` | Google Shopping Search | 2 | Search Google Shopping listings by query, such as a product name. |
| `POST /google/jobs` | Google Jobs Search | 2 | Search Google job listings using a role or keyword query. |
| `POST /google/books` | Google Books Search | 1 | Search Google Books using a title, author or keyword query. |
| `POST /google/finance` | Google Finance Search | 1 | Query Google Finance using a company or financial search term. |
| `POST /google/patents/detail` | Google Patent Details | 2 | Get one Google Patents record by publication number: title, abstract, claims, inventors, assignees and dates as published.. |
| `POST /google/play/search` | Google Play Search | 1 | Search apps on Google Play by keyword. |
| `POST /google/play/app` | Google Play App Details | 1 | Get one Google Play app by package name: name, developer, description, price, version, release dates and age rating from its store page.. |
| `POST /google/trends` | Google Trends | 2 | Google Trends API: up to five comma-separated terms as JSON, with interest over time for your time range and region, interest by region and related queries.. |
| `POST /google/trends/autocomplete` | Google Trends Autocomplete | 2 | Google Trends topic suggestions for a keyword, with each topic's type and identifier.. |
| `POST /google/trends/trending` | Google Trends Trending Now | 2 | Searches trending now on Google Trends for a country (US by default) over the last 24 hours.. |
| `POST /google/resolve` | Google Link Resolver | 0 | Free: turn Google's google.com/goto and /url result-link wrappers into the real page URLs, up to 50 links per request, from a list or a pasted search answer.. |
| `POST /duckduckgo/search` | DuckDuckGo Search | 1 | Search DuckDuckGo HTML results by query, with supported market and date filters. |

### Social media

| Endpoint | Name | Credits | What it returns |
| --- | --- | --- | --- |
| `POST /reddit/post` | Reddit Post & Comments | 2 | Retrieve full Reddit post content, author details, upvotes, and structured comment threads from a Reddit post URL.. |
| `POST /reddit/search` | Reddit Search | 1 | Search public Reddit posts and discussion threads across subreddits by keyword query.. |
| `POST /tiktok/post` | TikTok Post | 2 | Request a specific TikTok post using its ID and username. |
| `POST /tiktok/profile` | TikTok Profile | 2 | Request a TikTok profile using its username. |
| `POST /tiktok/search` | TikTok Search | 1 | Search TikTok videos by keyword: video links, captions, authors, view, like, comment and share counts, hashtags and covers, 16 per page by default.. |
| `POST /x/post` | X Post Details | 1 | Look up one X post by ID. |
| `POST /youtube/search` | YouTube Search | 1 | Search YouTube videos, Shorts, and creator channels with query and region parameters.. |
| `POST /youtube/transcripts` | YouTube Video Transcripts | 2 | Extract timestamped multi-language video transcripts and closed captions for a YouTube video ID.. |

### E-commerce

| Endpoint | Name | Credits | What it returns |
| --- | --- | --- | --- |
| `POST /ajio/product` | Ajio Product Details | 2 | Read an AJIO product page from its HTTPS /p/ URL. |
| `POST /amazon/product` | Amazon Product Details | 2 | Retrieve detailed Amazon product data including titles, multiple variant ASINs, merchant offers, availability, and specs by ASIN.. |
| `POST /amazon/search` | Amazon Product Search | 2 | Search Amazon product catalog by keyword query and domain. |
| `POST /amazon/autocomplete` | Amazon Search Autocomplete | 1 | Get Amazon query suggestions from a prefix. |
| `POST /apple/product` | Apple Product Details | 1 | Look up an Apple App Store app by numeric app ID or apps.apple.com app URL and country. |
| `POST /ebay/product` | eBay Product Details | 2 | Retrieve detailed eBay item data, current auction prices, seller ratings, and listing specifications by item ID.. |
| `POST /ebay/search` | eBay Product Search | 1 | Search eBay auction and Buy-It-Now listings by query. |
| `POST /flipkart/product` | Flipkart Product Details | 2 | Read a Flipkart item from a product URL containing /p/. |
| `POST /myntra/product` | Myntra Product Details | 2 | Read one Myntra product from its /buy URL. |
| `POST /myntra/search` | Myntra Search | 2 | Search Myntra with a query or a supported search URL. |
| `POST /walmart/product` | Walmart Product Details | 2 | Extract full Walmart product specification, pricing, variant details, and descriptions using Walmart item ID.. |
| `POST /walmart/search` | Walmart Product Search | 2 | Search Walmart retail inventory by keyword query. |
| `POST /walmart/autocomplete` | Walmart Search Autocomplete | 1 | Retrieve Walmart search suggestions for a query. |

### Web scraping

| Endpoint | Name | Credits | What it returns |
| --- | --- | --- | --- |
| `POST /web/user-agent` | User-Agent Generator | 1 | Generate desktop or mobile user-agent strings using user_agent_type and user_agent_count (1–5). |

### Real estate

| Endpoint | Name | Credits | What it returns |
| --- | --- | --- | --- |
| `POST /zillow/search` | Zillow Property Search | 2 | Read Zillow search results from a supported Zillow homes URL. |

### Maps and places

| Endpoint | Name | Credits | What it returns |
| --- | --- | --- | --- |
| `POST /google/maps/search` | Google Maps Search | 2 | Find Google Maps places using a query and location, such as coffee in Seattle. |
| `POST /google/maps/detail` | Google Maps Place Detail | 3 | Look up one Google Maps place by its place ID. |
| `POST /google/maps/reviews` | Google Maps Reviews | 2 | The first page of Google Maps reviews for a place (by data_id): rating, text, date, photos and reviewer details. |

Paused endpoints are not listed. The complete reference with every parameter and response field is at https://serpbase.dev/llms-full.txt; each page also exists as Markdown at its URL plus `.md` (for example https://serpbase.dev/docs/google_web_search.md). The OpenAPI document is at https://serpbase.dev/openapi.json. An MCP server for Claude, Cursor and other clients: https://serpbase.dev/docs/mcp-and-agents.