tierproxy

tierproxy — Python SDK

🚧 Preview release. Gateway is not yet generally available. Join the waitlist at [email protected]. SDK is functional but tierproxy doctor against a live gateway requires invitation.

[PyPI version] [Python versions] [Downloads] [CI] [codecov] [License: Apache 2.0] [OpenAPI 3.1] [MCP compatible]

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 tierproxyr = 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 TierProxywith 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

g = TierProxy(    monthly_budget_usd=200.0,    # raises BudgetExceededError before going over)

Power-user knobs

import httpxfrom tierproxy import TierProxyfrom 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:[email protected]:443

Error handling

Every SDK error inherits from tierproxy.TierProxyError and carries a request_id for support escalation:

from tierproxy import TierProxy, RateLimitErrorimport time
with TierProxy() as g:    try:        resp = g.get("https://example.com/page")    except RateLimitError as e:        time.sleep(e.retry_after or 5)        resp = g.get("https://example.com/page")

See Errors reference for the full HTTP-status-to-exception mapping.

AI agent integration

The SDK exposes its response models as JSON Schema and as pre-built tool definitions for Anthropic Claude and OpenAI function-calling:

import anthropicfrom tierproxy import TierProxy, schemas
with TierProxy() as gw:    anthropic.Anthropic().messages.create(        model="claude-sonnet-4-6",        max_tokens=1024,        tools=schemas.anthropic_tools(),        messages=[{"role": "user", "content": "How much quota is left?"}],    )

See the AI integration guide and the MCP server in examples/mcp_claude_desktop.md.

How tierproxy compares

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
• Per-request cost attribution — client.cost_for(resp) returns USD; lazy 30s cache, no per-request overhead
• Client-side response caching — cache_ttl=300, cache_max_response_size=262144 LRU with size cap
• Multi-provider auto-failover — auto_failover=True retries with next-best upstream on 429/5xx
• Rate-limit learning — client.rate_limits.get() surfaces gateway-aggregated 429s per target domain
• JA3/JA4 TLS rotation — per-upstream fingerprint randomization (gateway side; see tls-fingerprint guide)
• Cookie persistence — cookies stick to session_id across multi-step crawls
• Streaming responses — client.get(url, stream=True) returns iterator (large files, SSE)
• 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
• 8 framework integrations — LangChain, LlamaIndex, Crawl4AI, Playwright, Firecrawl, Browser-Use, CrewAI
• 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

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.