API Reference

Grab an API key from the dashboard (free: 1,000 credits a month, no card), install the official SDK for your language, and search:

# pip install serpdive
from serpdive import SerpDive

client = SerpDive()  # reads SERPDIVE_API_KEY
response = client.search("what happened between Trump and FIFA", answer=True)

print(response.answer)
for result in response.results:
    print(result.url, result.date, result.content)

// npm install serpdive
import { SerpDive } from "serpdive";

const client = new SerpDive(); // reads SERPDIVE_API_KEY
const response = await client.search("what happened between Trump and FIFA", {
  answer: true,
});

console.log(response.answer);
for (const result of response.results) {
  console.log(result.url, result.date, result.content);
}

Prefer plain HTTPS? The whole integration is one POST, from any language:

curl -X POST https://api.serpdive.com/v1/search \
  -H "Authorization: Bearer $SERPDIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "what happened between Trump and FIFA",
        "model": "mako" }'

The playground generates these snippets with your key preselected, and shows the live response next to them.

Two official clients, thin by design: they speak the exact /v1/search contract, add types, retries and nothing else.

Both read the key from the SERPDIVE_API_KEY environment variable (or take it explicitly), return typed responses, raise typed errors carrying the stable codes from the errors table, and retry transient failures (502/503) automatically, which is always safe because failed searches are never billed.

The Python client ships sync (SerpDive) and async (AsyncSerpDive). The TypeScript client has zero dependencies and runs anywhere fetch exists: Node 18+, Bun, Deno, edge runtimes.

SERPdive is also a hosted MCP server at https://mcp.serpdive.com: one tool, serpdive_search, that gives Claude Code, Claude Desktop, Cursor and any other MCP client the same extracted, answer-ready web results as the API. No install, nothing to run.

One command wires it into every agent on your machine, along with a skill that tells the agent which model to pick and how to keep the response small:

npx -y serpdive-cli init --key sd_live_YOUR_KEY

It finds Claude Code, Claude Desktop, Cursor, Windsurf, Codex, VS Code, Gemini CLI and OpenCode, and skips the ones you do not have. status and --dry-run change nothing; other MCP servers already in your config are left untouched. Or wire it by hand:

claude mcp add --transport http serpdive https://mcp.serpdive.com \
  --header "Authorization: Bearer sd_live_YOUR_KEY"

{
  "mcpServers": {
    "serpdive": {
      "url": "https://mcp.serpdive.com/?key=sd_live_YOUR_KEY"
    }
  }
}

Auth is your regular API key, either as an Authorization: Bearer header or as a ?key= parameter on the server URL for clients that only take a URL. Searches through MCP are billed exactly like API calls, same credits, same rate limits.

Every request carries your key in the Authorization header: Bearer sd_live_…. Keys are created, revealed and revoked in API Keys; revocation takes effect immediately. At creation a key can optionally get an expiration date (it stops authenticating past it, same 401 as a revoked key) and a monthly credit limit of its own — a guardrail for a key you deploy somewhere you don't fully control. A missing, expired or unknown key gets a 401 with missing_api_key or invalid_api_key: the search never runs, and nothing is billed.

Official package: `langchain-serpdive`. One tool class, sync and async, built on the Python SDK.

# pip install langchain-serpdive
from langchain_serpdive import SerpdiveSearch

tool = SerpdiveSearch()  # reads SERPDIVE_API_KEY
tool.invoke({"query": "latest developments in solid state batteries"})

# or hand [SerpdiveSearch()] to any LangChain / LangGraph agent as its tools list

Official package: `llama-index-tools-serpdive`. Results come back as Documents (text = extracted page content, metadata = url/title/date), ready for agents or a RAG pipeline.

# pip install llama-index-tools-serpdive
from llama_index_tools_serpdive import SerpdiveToolSpec

spec = SerpdiveToolSpec()  # reads SERPDIVE_API_KEY
documents = spec.serpdive_search("latest developments in solid state batteries")

# in an agent: tools=SerpdiveToolSpec().to_tool_list()

The TypeScript SDK plugs straight into an AI SDK tool: the model decides when to search, the response is already LLM-sized.

// npm install ai serpdive zod
import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";
import { SerpDive } from "serpdive";

const serpdive = new SerpDive(); // reads SERPDIVE_API_KEY

const { text } = await generateText({
  model: "anthropic/claude-sonnet-5",
  prompt: "What changed in the EU AI Act this month?",
  stopWhen: stepCountIs(5),
  tools: {
    serpdive_search: tool({
      description:
        "Search the live web for current information. Returns extracted, " +
        "answer-ready page content (url, title, date, text), not links.",
      inputSchema: z.object({
        query: z.string().describe("The search, in any language"),
      }),
      execute: async ({ query }) => serpdive.search(query),
    }),
  },
});

No package needed: declare the function, run the search when the model calls it, feed the JSON back.

# pip install openai serpdive
import json
from openai import OpenAI
from serpdive import SerpDive

client, serpdive = OpenAI(), SerpDive()

tools = [{
    "type": "function",
    "name": "serpdive_search",
    "description": "Search the live web for current information. Returns "
                   "extracted, answer-ready page content, not links.",
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
}]

response = client.responses.create(
    model="gpt-5", input="What changed in the EU AI Act this month?", tools=tools
)
for item in response.output:
    if item.type == "function_call":
        result = serpdive.search(json.loads(item.arguments)["query"])
        # send result.raw back as the function_call_output, then re-run

Same idea with the Claude API — or skip the plumbing entirely: Claude clients can use our hosted MCP server directly.

# pip install anthropic serpdive
import anthropic
from serpdive import SerpDive

client, serpdive = anthropic.Anthropic(), SerpDive()

tools = [{
    "name": "serpdive_search",
    "description": "Search the live web for current information. Returns "
                   "extracted, answer-ready page content, not links.",
    "input_schema": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
}]

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What changed in the EU AI Act this month?"}],
)
for block in message.content:
    if block.type == "tool_use":
        result = serpdive.search(block.input["query"])
        # send result.raw back as a tool_result block, then re-run

POST /v1/search with a JSON body. Four parameters; everything else is decided for you:

Localization is automatic. The query's language picks where we search: a German query searches the German-language web, a Japanese one the Japanese web, whoever and wherever the caller is. There is no country knob to set.

Set a generous client timeout. Mako answers in a few seconds; Moby reads whole pages and can take substantially longer on heavy sources. We recommend an 80-second client timeout; it's what our own playground uses.

A successful search returns 200 with this shape, nothing else, ever:

{
  "query": "what happened between Trump and FIFA",
  "model": "mako",
  "response_time_ms": 2641,
  "results": [
    {
      "url": "https://www.reuters.com/sports/soccer/…",
      "title": "Trump, FIFA's Infantino unveil …",
      "date": "2026-07-11",
      "content": "The announcement came during a joint press conference … [the fact-carrying sentences of the page]"
    },
    {
      "url": "https://www.bbc.com/sport/football/…",
      "title": "What the deal means for the 2026 World Cup",
      "content": "…"
    }
  ]
}

Every result carries content that speaks to the query — never a bare link, never a placeholder. A source we could get nothing usable from is simply absent rather than padded out. Tracking parameters (utm_*, click IDs…) are stripped from URLs, so what you cite is clean.

Asking for the answer looks like this:

{ "query": "who won the 2026 Champions League final",
  "model": "moby",
  "answer": true }

Every failure returns a JSON body with two fields: error, a stable machine-readable code, and message, a human sentence that says what to do about it:

{
  "error": "invalid_api_key",
  "message": "This API key is invalid or was revoked. Manage your keys at https://serpdive.com/dashboard/keys"
}

Failed searches are never billed. Any non-200 response costs zero credits, whatever the reason.

Rule of thumb: start with Mako. Reach for Moby when the task is synthesis: briefs, comparisons, anything where a missing paragraph changes the conclusion. Krill is for volume without a budget — it answers most questions, on fewer sources and without the written answer.

A Krill search is free and never touches your quota — that is what makes it unlimited. A Mako search costs 1 credit, a Moby search 1.5. The answer is always included, and failures are free. Every account gets 1,000 credits a month; they renew monthly on your signup date (billing date on paid plans) and don't roll over. Live consumption is on your Usage page, plans and pricing on Billing.

When the month’s credits run out, further requests return 429 monthly_quota_exceeded until they reset; blocked calls are never billed. On Pay as you go there is no monthly cap by default — usage is metered and invoiced at the end of each billing cycle instead; you can set an optional monthly spend limit in Billing and requests 429 past it, same as a quota. A key created with its own monthly limit returns 429 key_limit_exceeded once that limit is spent — the rest of your keys keep working. Rate limits are 5 requests per second and 200 per minute, on every plan; beyond them requests return 429 rate_limit_exceeded with a retry-after header, and cost nothing. Separately, an account can hold 5 searches in flight at once on Mako and Moby, 1 on Krill — that bounds simultaneous work rather than arrival rate, and going past it returns 429 too_many_concurrent_requests. Searching at serious scale? Talk to us.