quantumproxies — Python SDK for the QuantumProxies API

Scrape any page to clean Markdown, run structured Google/Bing/DuckDuckGo searches, crawl and map whole sites, run 74 ready-made Collectors (Amazon, Google Maps, LinkedIn jobs, app stores…), build datasets from a plain-language prompt — everything through QuantumProxies' residential proxy network with real-browser TLS fingerprints. Pay per successful call; blocked pages cost nothing.

pip install quantumproxies

Quickstart

from quantumproxies import QuantumProxies

client = QuantumProxies()  # reads QUANTUMPROXIES_API_KEY from the environment

page = client.scrape("https://example.com")
print(page["title"], page["engine"])
print(page["content"])          # the page as clean Markdown

Get a free API key at quantumproxies.io — every account includes free monthly usage, no card required. Set it once:

export QUANTUMPROXIES_API_KEY=qp_live_your_key_here

What's in the box

Every REST endpoint, one method each — responses come back with the API envelope already unwrapped:

# Structured search — 3 engines, 17 verticals, SerpApi-compatible JSON
serp = client.search("best espresso machine", country="us", num=20)
for r in serp["organic"]:
    print(r["rank"], r["title"], r["link"])

# SERP → citation-ready Markdown context for an AI prompt
ctx = client.search_and_read("latest EU AI act status", top_n=3)

# Map a site's URLs in seconds (sitemaps + homepage links)
urls = client.map("https://stripe.com", search="/blog")

# Async crawl — wait=True polls until it settles and returns the pages
job = client.crawl("https://docs.python.org", limit=30, depth=2, wait=True)

# Batch-scrape known URLs
job = client.batch(["https://a.example", "https://b.example"], wait=True)

# CSS/AI extraction on one page
data = client.scrape(
    "https://books.toscrape.com",
    extract={"titles": {"selector": "h3 a", "attr": "title", "all": True}},
)

# Learn selectors once with an LLM, then scrape the same layout for free
parser = client.generate_parser(
    "https://news.ycombinator.com",
    fields={"titles": "every story title, as a list"},
)

# 74 ready-made Collectors — semantic input instead of URLs
places = client.run_collector(
    "google_maps_places", keyword="dentist", location="Austin, TX", max_results=20
)

# Dataset from a prompt (validated rows, budget-capped)
ds = client.create_dataset(
    "coffee roasters in Portland with email and phone",
    limits={"max_rows": 50, "max_cost_usd": 2},
    wait=True,
)

# Proxy endpoints of every type — residential, mobile, datacenter, ISP, IPv6
plans = client.list_proxies(active=True)
proxies = client.generate_proxies(plans["proxies"][0]["orderId"], country="us", quantity=5)

Web Unlocker

unlock() replays any HTTP request — method, headers, body — through a residential exit with a real browser TLS fingerprint, retries on a fresh IP when the target blocks it, and escalates a blocked GET to a real browser. You get the raw response back: status, headers, body, finalUrl.

r = client.unlock("https://www.example-shop.com/item/42", country="us")
if r["blocked"]:
    print(r["blockClass"], r.get("vendor"), r.get("blockReason"))  # e.g. "waf", "cloudflare"
else:
    print(r["status"], r["body"][:200])

# Force a real browser render and wait for the price to appear
page = client.unlock(
    "https://www.example-shop.com/item/42",
    render="html", wait_for_selector=".price", wait_ms=1500,
)

A still-blocked page is never returned as a silent 200: it comes flagged with blocked: true (pass fail_on_block=True to get an error instead). Interactive captchas are not solved — they arrive with blockClass: "captcha". Billed per GB of the tier's prepaid unlocker balance (usage in the response).

Errors and retries

Failures raise QuantumProxiesError with .status, .message and .payload. Connection errors and HTTP 429 are retried with backoff; billable calls are never re-sent after a response was received, so nothing gets double-billed behind your back.

from quantumproxies import QuantumProxies, QuantumProxiesError

try:
    QuantumProxies(api_key="qp_live_wrong").scrape("https://example.com")
except QuantumProxiesError as err:
    print(err.status, err.message)

Also available

• MCP server for Claude, Cursor and any MCP client: npx -y quantumproxies-mcp exposes the same 25 tools to AI agents.
• REST reference: quantumproxies.io/data-api

MIT licensed.