tierproxy 0.1.0

Official Python SDK for tierproxy — premium multi-provider proxy infrastructure for AI/ML pipelines.

tierproxy — Python SDK

Premium multi-provider proxy infrastructure for AI/ML pipelines. Built for engineers who measure cost, latency, and success rate twice — and write Python.

Install

pip install tierproxy

Quickstart — five-second flavor

import tierproxy
r = tierproxy.get("https://example.com", country="US")
print(r.text)

That's it. (Set TIERPROXY_API_KEY env var first.)

Three lines, persistent session

from tierproxy import TierProxy
with TierProxy() as g:
    print(g.me.get().client_id)
    r = g.get("https://example.com", country="US", session_id="s1")

Auto-pick the cheapest healthy upstream every request

g = TierProxy(routing="cheapest")  # also: "fastest", "most_reliable", "balanced"
g.get("https://example.com")     # picks via /v1/health/upstreams under the hood

Cost guardrails + 80% usage alert

def alert(pct: float) -> None:
    print(f"Used {pct:.0f}% of monthly quota")

g = TierProxy(
    monthly_budget_usd=200.0,    # raises BudgetExceededError before going over
    on_usage_pct=80,             # fires the callback once you cross 80%
    on_usage_callback=alert,
)

Power-user knobs

import httpx
from tierproxy import TierProxy
from tierproxy.retry import RetryPolicy

g = TierProxy(
    api_key="tp_live_...",
    base_url="https://my-self-hosted-gw:8444",
    timeout=10.0,
    retry_policy=RetryPolicy(max_retries=5, retry_on_status=frozenset({500, 502})),
    http_client=httpx.Client(verify=False),  # custom transport
    user_agent_suffix="my-app/2.3",          # attribution
)

Raw modes (Playwright, curl, etc.)

from tierproxy import ProxyURL

p = ProxyURL(api_key="tp_live_...", country="US", mode="username_encoding")
print(p.http_url())  # http://customer-tp_live_...-cc-US:[e-mail]:443

How tierproxy compares

	tierproxy	Smartproxy SDK	Bright Data SDK	Oxylabs SDK	DataImpulse
Multi-provider routing	✅	❌	❌	❌	❌
Client-side smart selector (cost-aware)	✅	❌	❌	❌	❌
Live usage streaming (SSE)	✅	❌	❌	❌	❌
MCP server (Claude/Cursor/Cline)	✅	❌	❌	❌	❌
OpenTelemetry built-in	✅	❌	❌	❌	❌
Sync + async parity	✅	partial	partial	partial	partial
AI/ML framework examples shipped	10	0	1	0	0
Type-safe (Pydantic v2 + mypy strict)	✅	❌	❌	partial	❌
OpenAPI 3.1 spec	✅	❌	❌	❌	❌
Pip-installable CLI (tierproxy doctor)	✅	❌	❌	❌	❌
License	Apache 2.0	proprietary	proprietary	proprietary	proprietary

Features

• Five-second quickstart — import tierproxy; tierproxy.get(url, country="US")
• Layered API — five integration levels from one-liner to power-user knobs
• Smart routing — routing="cheapest" auto-picks healthy upstream per request
• Cost guardrails — monthly_budget_usd= refuses requests that would exceed budget
• Usage alerts — on_usage_pct=80 fires callback at 80% of quota
• Live SSE stream — for delta in g.usage.stream() tails month-to-date bytes
• MCP server — tierproxy-mcp exposes proxy as tools to Claude/Cursor/Cline
• 10 framework integrations — LangChain, LlamaIndex, Crawl4AI, Playwright, Firecrawl, Browser-Use, ScrapeGraphAI, CrewAI, GPT-Researcher
• OpenTelemetry opt-in — pip install tierproxy[otel] for distributed tracing
• Geo + sticky sessions — countries, cities, 1-1440min session pins
• Dual URL syntax — headers (httpx/requests) AND username-encoding (Playwright)
• Type-safe end-to-end — Pydantic v2 models, mypy strict, full IDE autocomplete

See examples/ for LangChain/LlamaIndex/Crawl4AI/Playwright and examples/levels.py for a runnable demo of every level.

Use with your favorite AI/agent framework

Framework	Example	Notes
LangChain	with_langchain.py	RAG document loaders through proxy
LlamaIndex	with_llamaindex.py	SimpleWebPageReader through proxy
Crawl4AI	with_crawl4ai.py	Playwright crawler + tierproxy
Firecrawl (hot)	with_firecrawl.py	Self-hosted Firecrawl + residential IPs
Browser-Use (hot)	with_browser_use.py	LLM-driven autonomous browser
CrewAI (hot)	with_crewai.py	Multi-agent scraper crew + cost-aware routing
ScrapeGraphAI	with_scrapegraphai.py	LLM-driven extraction in plain English
GPT-Researcher	with_gpt_researcher.py	Multi-region research with geo rotation
Playwright	with_playwright.py	Direct Playwright with tierproxy
MCP (Claude/Cursor/Cline/Windsurf) (unique)	mcp_claude_desktop.md	Native tool integration via tierproxy-mcp

MCP server (Claude Desktop / Cursor / Cline / Windsurf)

pip install tierproxy[mcp]

Then add to your MCP client config:

{
  "mcpServers": {
    "tierproxy": {
      "command": "tierproxy-mcp",
      "env": { "TIERPROXY_API_KEY": "tp_live_..." }
    }
  }
}

Now your AI assistant can call fetch_url(url, country="US"), inspect health and usage, and route through the cheapest healthy upstream — no glue code, no httpx imports, no boilerplate.