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"}'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/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.
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
}