tierproxy — Python SDK

🚧 Preview release. Gateway is not yet generally available. Join the waitlist at hello@tierproxy.com. SDK is functional but tierproxy doctor against a live gateway requires invitation.

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

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

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:x@gw.tierproxy.com:443

Error handling

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

from tierproxy import TierProxy, RateLimitError
import 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 anthropic
from 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 int

... View full README on GitHub