Python SDK

The serpex package is the official Python SDK for the Serpex API. Requires Python 3.8+.

Package: serpex on PyPI — v2.6.0

Installation

pip install serpex

Or with Poetry:

poetry add serpex

Initialize the Client

from serpex import SerpexClient

client = SerpexClient("sk_your_api_key")

The constructor accepts an optional base_url argument (defaults to https://api.serpex.dev).

Search

from serpex import SerpexClient

client = SerpexClient("sk_your_api_key")

results = client.search({
    "q": "python tutorial",
})

print(results.results[0].title)
print(results.results[0].url)
print(results.metadata.credits_used)

Using SearchParams for Type Safety

from serpex import SerpexClient, SearchParams

client = SerpexClient("sk_your_api_key")

params = SearchParams(q="machine learning")
results = client.search(params)

print(results.results[0].title)

Set include_content to fetch each top result's page and get it back as markdown — handy for feeding results straight into an LLM without a separate crawl call. It's best-effort (roughly 79% of requested results come back with content; blocked or robots.txt-disallowed pages return content_error instead) and costs more than a plain search — see pricing.

params = SearchParams(
    q="latest AI news",
    include_content=True,
    content_results=5,  # 5 (default, 2 credits) or 10 (4 credits)
)
results = client.search(params)

for r in results.results:
    if r.content:
        print(f"{r.title}: {len(r.content)} chars of markdown")
    elif r.content_error:
        print(f"{r.title}: content unavailable — {r.content_error}")

print(f"Content delivered: {results.metadata.content_delivered}/{results.metadata.content_requested}")

Search Parameters

from dataclasses import dataclass
from typing import Literal, Optional

@dataclass
class SearchParams:
    q: str                                    # Required. Max 500 characters.
    include_content: bool = False             # Fetch page content (markdown) for top results.
    content_results: Literal[5, 10] = 5       # Only used when include_content is True.

Extract

from serpex import SerpexClient

client = SerpexClient("sk_your_api_key")

# Extract as Markdown — ideal for LLM processing
result = client.extract({
    "urls": ["https://example.com", "https://httpbin.org"],
})

for r in result.results:
    if r.success:
        print(f"{r.url}: {len(r.markdown)} characters")
    else:
        print(f"{r.url}: failed — {r.error}")

print(f"Credits used: {result.metadata.credits_used}")

Extract with Stealth Mode

# Stealth mode for sites with bot protection — costs 5 credits per URL
stealth_result = client.extract({
    "urls": ["https://protected-site.com/page"],
    "stealth": True,
    "format": "html",
})

print(stealth_result.results[0].html)

Using ExtractParams for Type Safety

from serpex import SerpexClient, ExtractParams

client = SerpexClient("sk_your_api_key")

params = ExtractParams(
    urls=["https://example.com", "https://httpbin.org"],
    stealth=False,
    format="markdown",
)
result = client.extract(params)

Extract Parameters

@dataclass
class ExtractParams:
    urls: list[str]       # Required. Max 10 URLs per request.
    stealth: bool = False # 5 credits/URL when True.
    format: str = "markdown"  # "markdown" | "html"

Error Handling

from serpex import SerpexClient, SerpApiException

client = SerpexClient("sk_your_api_key")

try:
    results = client.search({"q": "test query"})
except SerpApiException as e:
    print(f"API error: {e}")
    print(f"Status code: {e.status_code}")
    print(f"Details: {e.details}")

Requirements

Python 3.8+
requests