Send POST JSON requests and pass your API key in the X-API-Key header. The response body is JSON for both success and failure cases.
Common response envelope
Per-request catalog price; executed failures may be charged
support trace id
curl -X POST https://api.serpbase.dev/google/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"q":"openai realtime api","hl":"en","gl":"us","device":"default"}'Automatic account QPS upgrades
After an eligible top-up is confirmed as credited, cumulative USD thresholds raise account QPS to at least: $3 → 2, $50 → 5, $200 → 15, $1,000 → 50, $10,000 → 500. Below $3, your current account limit is unchanged. Upgrades only raise the limit; they never lower an existing higher limit. This is not unlimited QPS.
| Cumulative eligible top-ups (USD) | Upgrade to at least (QPS) |
|---|---|
| ≥ $3 | 2 QPS |
| ≥ $50 | 5 QPS |
| ≥ $100 | 10 QPS |
| ≥ $200 | 15 QPS |
| ≥ $1,000 | 50 QPS |
| ≥ $10,000 | 500 QPS |
Only USD credit-pack (credit_pack) and automatic top-up (auto_topup) payments confirmed as credited count. Subscriptions (including Starter Boost), gifts and gift codes do not count. Credit balances are not cumulative USD payments. Non-USD payments are not counted as USD without currency conversion.
All API keys, products and gateways for the same account share one QPS limit. Creating more keys does not increase it.
Eligible top-ups automatically raise account QPS after confirmed crediting, not merely after returning from checkout. The current limit is the server-reported value shown in your account; API key synchronization may briefly lag.
Use the open-source MCP server or portable agent skill when you want Claude, Codex, Cursor, Cline/Roo, opencode, or other agents to call SerpBase directly with your API key.
MCP integration for AI clients that support tools. Check this deployment’s endpoint catalog before selecting a search tool.
Best for Claude, Codex, Cursor, Cline/Roo, Continue, and other MCP-capable clients.
Portable skill folder and shell fallback for agents that read local instructions or need a lightweight script instead of running an MCP server.
Best for Codex skills, Claude Code memory, opencode, OpenClaw-style agents, and shell-capable workflows.
{
"mcpServers": {
"serpbase": {
"command": "python",
"args": ["-m", "serpbase_mcp"],
"env": {
"SERPBASE_API_KEY": "your_api_key"
}
}
}
}Use $serpbase-skill to search Google through SerpBase and return cited structured results.Retrieve the current credit balance for the account that owns an active API key. This request does not consume search credits.
/account/creditsPass the key in the X-API-Key header. API keys in URL query parameters are not accepted.
curl https://api.serpbase.dev/account/credits \
-H "X-API-Key: your_api_key"{
"status": 0,
"credits": 12345,
"permanent_credits": 10000,
"expiring_credits": 2345,
"expiring_expires_at": 1798761600
}The endpoint is limited to 60 requests per minute per account. expiring_expires_at is a Unix timestamp in seconds and is 0 when no limited-time credits are active.
Successful endpoint responses return the same top-level metadata. Endpoint-specific data lives in one result key such as organic, images, news, videos, places, or place.
statusnumberrequired
Business status code. 0 means success.
request_idstringrequired
Stable request identifier for support, retries, and log correlation.
elapsed_msnumberrequired
Gateway-observed execution duration in milliseconds.
credits_chargednumberrequired
Credits charged after refund logic is applied.
search_typestringrequired
Resolved type: search, images, news, videos, maps_search, or maps_detail.
/google/searchGoogle-style organic results plus rich SERP modules.
/google/image/searchImage result URLs, thumbnails, source pages, and domains.
/google/news/searchNews articles with publisher, time text, snippets, and thumbnails.
/google/videos/searchVideo result links with source, duration, time, and thumbnails.
/google/maps/searchLocal place search with coordinates, contact data, categories, hours, and photos when available.
/google/maps/detailSingle place details by Google Maps feature_id.
/google/searchSearch
Google-style organic results plus rich SERP modules.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
device"default" | "pc" | "mobile"optional
Google Search only. Use default for automatic routing, pc for desktop sessions, or mobile for mobile sessions.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
organicOrganicResult[]When organic results are parsed.
Organic search results.
featured_snippetFeaturedSnippetWhen Google shows a featured snippet.
Featured snippet answer card, returned separately from organic results.
top_storiesTopStory[]When the SERP contains top stories.
Top stories module.
people_also_askPAA[]When People Also Ask is present.
Question, answer, and source links.
knowledge_graphKnowledgeGraphWhen a knowledge panel is parsed.
Entity panel data.
related_searchesstring[]When related search suggestions are found.
Related search queries.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringrequired
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
display_linkstringWhen Google display text is present.
Raw Google display link text.
snippetstringWhen a snippet is parsed.
Organic result summary.
datestringWhen Google includes a date in the snippet.
Raw date text extracted from snippet.
published_atstringAlias for parsed date when available.
Normalized date alias.
iconstringWhen a favicon/image is exposed.
Result icon URL.
sitelinks{ title, link, url, source_url?, display_url? }[]When sitelinks are present.
Nested sitelinks for the organic result.
curl -X POST https://api.serpbase.dev/google/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "python asyncio",
"hl": "en",
"gl": "us",
"page": 1,
"device": "default"
}'Search grounding, SEO checks, answer extraction.
Search can also return ai_overview, weather, finance, flight, and result_stats when those modules appear in the SERP.
/google/image/searchImages
Image result URLs, thumbnails, source pages, and domains.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
imagesImageResult[]When image results are parsed.
Google Images results.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringWhen image title or alt text is parsed.
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
image_urlstringrequired
Full image URL.
thumbnail_urlstringWhen Google exposes a thumbnail.
Thumbnail URL.
thumbnailstringAlias for thumbnail_url when available.
Normalized thumbnail alias.
sourcestringWhen source text is parsed.
Image source label.
domainstringWhen source page domain can be derived.
Source page domain.
curl -X POST https://api.serpbase.dev/google/image/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "iphone 15 pro blue",
"hl": "en",
"gl": "us",
"page": 1
}'Visual search, product monitoring, image source discovery.
Some Google Images payload shapes expose rank/link but not every normalized alias. Treat url, display_url, source_url, position, and thumbnail as optional.
/google/news/searchNews
News articles with publisher, time text, snippets, and thumbnails.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
newsNewsResult[]When news results are parsed.
Google News results.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringrequired
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
sourcestringWhen publisher text is parsed.
Publisher/source label.
timestringWhen Google exposes time text.
Raw published time text.
published_atstringAlias for parsed time when available.
Normalized published time alias.
snippetstringWhen a snippet is parsed.
Article summary snippet.
thumbnail_urlstringWhen Google exposes a thumbnail.
Thumbnail URL.
thumbnailstringAlias for thumbnail_url when available.
Normalized thumbnail alias.
curl -X POST https://api.serpbase.dev/google/news/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "apple event",
"hl": "en",
"gl": "us",
"page": 1
}'Brand monitoring, trend tracking, media discovery.
Source and time are parsed from compact Google metadata text, so clients should treat both as optional.
/google/videos/searchVideos
Video result links with source, duration, time, and thumbnails.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
videosVideoResult[]When video results are parsed.
Google Videos results.
ranknumberrequired
1-based ranking position in this response.
positionnumberAlias for rank when available.
Normalized rank alias for clients that expect position.
titlestringrequired
Result title.
linkstringrequired
Primary link returned by the parser.
urlstringPresent for normalized result links.
Canonical target URL, usually the same value as link.
source_urlstringOnly when Google redirect/source URL is observed.
Original Google URL kept for debugging and provenance.
display_urlstringWhen Google display text or a domain can be derived.
Display URL or source domain.
sourcestringWhen source/channel can be parsed.
Video source or channel label.
durationstringWhen duration appears in result text.
Video duration text.
timestringWhen posted time can be parsed.
Raw posted time text.
published_atstringAlias for parsed time when available.
Normalized posted time alias.
thumbnail_urlstringWhen Google exposes a thumbnail.
Thumbnail URL.
thumbnailstringAlias for thumbnail_url when available.
Normalized thumbnail alias.
curl -X POST https://api.serpbase.dev/google/videos/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "python asyncio tutorial",
"hl": "en",
"gl": "us",
"page": 1
}'Video search, tutorial discovery, media monitoring.
If no dedicated video cards are parsed, the parser falls back to news-style extraction for compatible Google layouts.
/google/maps/searchMaps Search
Local place search with coordinates, contact data, categories, hours, and photos when available.
qstringrequired
Search query string.
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
pagenumberoptional
1-based page number. Defaults to 1.
latnumberoptional
Map center latitude. Must be sent together with lng.
lngnumberoptional
Map center longitude. Must be sent together with lat.
zoomnumberoptional
Map zoom from 1 to 21. Defaults to 14 when coordinates are sent.
querystringrequired
Normalized query from the request.
pagenumberrequired
Current 1-based page number.
placesMapsPlace[]When local places are parsed.
Local place results.
positionnumberMaps Search only.
Place rank in the local result list.
namestringrequired
Place name.
titlestringrequired
Alias for name.
feature_idstringrequired
Google Maps feature id.
place_idstringWhen Google exposes it.
Google place id.
data_idstringAlias for feature_id.
Maps data id.
cidstringDerived from feature_id when possible.
Google CID.
kgmidstringWhen present in Maps payload.
Knowledge graph machine id.
google_maps_urlstringWhen Google exposes a Maps URL.
Google Maps URL.
urlstringgoogle_maps_url or website fallback.
Primary place URL.
ratingnumberWhen rating is present.
Google rating.
typesstring[]When categories are present.
Place type labels.
categoryobjectWhen category block is parsed.
Structured category data.
addressstringWhen address is present.
Formatted address.
address_componentsobjectWhen components are present.
Street, city, postal code, country code.
plus_codeobjectWhen plus code is present.
Global and compound plus codes.
phonestringWhen phone is present.
Local phone number.
phone_internationalstringWhen present.
International phone number.
phone_uristringWhen present.
Telephone URI.
websitestringWhen website is present.
Business website.
website_domainstringWhen website domain is present.
Business website domain.
latitudenumberWhen coordinates are present.
Latitude.
longitudenumberWhen coordinates are present.
Longitude.
imagestringWhen image is present.
Primary place image.
thumbnailstringAlias for image when available.
Primary image alias.
photosMapsPhoto[]When photos are parsed.
Photo id, URL, size, and optional coordinates.
hoursRecord<string,string>When hours are parsed.
Opening hours by day.
open_statusobjectWhen status is present.
Open status text and current hours.
attributesobject[]When attributes are parsed.
Grouped place attributes.
related_placesobject[]When related places are present.
Related places from Maps payload.
short_descriptionstringWhen description block is present.
Short place description.
descriptionstringWhen description block is present.
Longer place description.
snippetstringshort_description or description fallback.
Normalized text summary.
timezonestringWhen present.
Place timezone.
regionstringWhen present.
Region label.
country_codestringWhen present.
Country code.
languagestringWhen present.
Language code from Maps payload.
curl -X POST https://api.serpbase.dev/google/maps/search \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"q": "coffee",
"hl": "en",
"gl": "us",
"page": 1,
"lat": 37.7749,
"lng": -122.4194,
"zoom": 14
}'Local discovery, store lookup, geo-targeted auditing.
lat and lng must be sent together. zoom is valid only with coordinates and defaults to 14.
/google/maps/detailMaps Detail
Single place details by Google Maps feature_id.
feature_idstringrequired
Use the feature_id field returned by Maps Search place results. It is formatted like 0x...:0x....
hlstringoptional
Language code. Defaults to en.
glstringoptional
Country code. Defaults to us.
feature_idstringrequired
Feature id resolved from the Maps detail request.
pagenumberrequired
Always 1 for maps detail.
placeMapsPlaceWhen place details are parsed.
Single place detail object.
positionnumberMaps Search only.
Place rank in the local result list.
namestringrequired
Place name.
titlestringrequired
Alias for name.
feature_idstringrequired
Google Maps feature id.
place_idstringWhen Google exposes it.
Google place id.
data_idstringAlias for feature_id.
Maps data id.
cidstringDerived from feature_id when possible.
Google CID.
kgmidstringWhen present in Maps payload.
Knowledge graph machine id.
google_maps_urlstringWhen Google exposes a Maps URL.
Google Maps URL.
urlstringgoogle_maps_url or website fallback.
Primary place URL.
ratingnumberWhen rating is present.
Google rating.
typesstring[]When categories are present.
Place type labels.
categoryobjectWhen category block is parsed.
Structured category data.
addressstringWhen address is present.
Formatted address.
address_componentsobjectWhen components are present.
Street, city, postal code, country code.
plus_codeobjectWhen plus code is present.
Global and compound plus codes.
phonestringWhen phone is present.
Local phone number.
phone_internationalstringWhen present.
International phone number.
phone_uristringWhen present.
Telephone URI.
websitestringWhen website is present.
Business website.
website_domainstringWhen website domain is present.
Business website domain.
latitudenumberWhen coordinates are present.
Latitude.
longitudenumberWhen coordinates are present.
Longitude.
imagestringWhen image is present.
Primary place image.
thumbnailstringAlias for image when available.
Primary image alias.
photosMapsPhoto[]When photos are parsed.
Photo id, URL, size, and optional coordinates.
hoursRecord<string,string>When hours are parsed.
Opening hours by day.
open_statusobjectWhen status is present.
Open status text and current hours.
attributesobject[]When attributes are parsed.
Grouped place attributes.
related_placesobject[]When related places are present.
Related places from Maps payload.
short_descriptionstringWhen description block is present.
Short place description.
descriptionstringWhen description block is present.
Longer place description.
snippetstringshort_description or description fallback.
Normalized text summary.
timezonestringWhen present.
Place timezone.
regionstringWhen present.
Region label.
country_codestringWhen present.
Country code.
languagestringWhen present.
Language code from Maps payload.
curl -X POST https://api.serpbase.dev/google/maps/detail \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"feature_id": "0x8085809c2c6fdc63:0x4b3f2d70e4f5a123",
"hl": "en",
"gl": "us"
}'Place enrichment, local CRM data, detail pages.
Use the feature_id field from a Maps Search place result to request a detail record. A well-formed but unknown feature_id returns status 1004.
errorstringrequired
Human-readable failure message.
Request completed successfully.
Missing or invalid body or parameters.
Missing, invalid, or revoked API key.
Resource not found. For Maps Detail, the feature_id is well-formed but no place was found.
Account balance is not enough.
QPS or concurrency limit exceeded.
Unexpected internal server error.
Worker returned an upstream fetch or parse error.
No worker session is available.
Gateway timed out waiting for a worker result.
{
"status": 1001,
"error": "unauthorized",
"request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
"elapsed_ms": 0,
"credits_charged": 0
}