tierproxy Python SDK

Official Python SDK for tierproxy — a premium multi-provider proxy gateway built for AI/ML data-collection pipelines. The SDK wraps the public REST API (/v1/me, /v1/usage/me, /v1/usage/me/stream, /v1/health/upstreams) and ships ready-to-use adapters for the most popular Python HTTP clients and scraping frameworks.

Contents

• Quickstart
  • 1. Install
  • 2. Configure your API key
  • 3. Inspect your account
  • 4. Pull month-to-date usage
  • 5. Stream live usage deltas
  • 6. Check upstream health
  • 7. Build a proxy URL for your favourite HTTP client
  • Async
  • Next steps
• The integration ladder
  • Level 0 — One-liner
  • Level 1 — Persistent client
  • Level 2 — Smart routing
  • Level 3 — Guardrails
  • Level 4 — Transport / retry overrides
  • Level 5 — Raw modes
• Cookbook — recipes
  • 1. Scrape a news site through residential IPs
  • 2. RAG ingestion through tierproxy (LangChain)
  • 3. Playwright browser through tierproxy
  • 4. Live cost dashboard (terminal)
  • 5. MCP integration (Claude Desktop / Cursor / Cline / Windsurf)
• Response caching
  • Motivation
  • Usage
  • Caveats
  • When NOT to use
  • Source
• Per-request cost attribution
  • Motivation
  • Usage
  • How it works
  • Caveats
  • Cost of the cost feature itself
  • Source
• Multi-provider auto-failover
  • Usage
  • When to use
  • When NOT to use
  • Caveats
  • Source
• Rate-limit learning
  • Usage
  • How it works
  • Limitations (honest doc)
  • When to use
  • When NOT to use
  • Source
• JA3/JA4 TLS fingerprint rotation
  • Motivation
  • Usage
  • How it works
  • Caveats
  • Source
• Cookies + streaming responses
  • Cookies persistence
  • Streaming responses
  • Source
• Observability with OpenTelemetry
• tierproxy vs the field
  • When to pick which
• FAQ
  • How do I get an API key?
  • Sync vs async — which should I use?
  • Does routing="cheapest" always pick the cheapest upstream?
  • How is monthly cost calculated?
  • Why does my with_browser_use.py keep getting blocked?
  • Does the CLI work without an API key?
  • What happens at month-end with usage rollovers?
  • Can I use tierproxy with self-hosted gateway?
  • What’s the difference between tierproxy.get() and client.get()?
  • How do I trace SDK calls with my existing OpenTelemetry setup?
  • Why does my IDE not autocomplete tierproxy methods?
  • Can I revoke an API key?
  • What’s the rate limit?
  • How do I report a bug?
  • Is the gateway code open-source?
• Migrating to tierproxy
  • Migrating from v0.1.x to v0.2.0
  • From Smartproxy
  • From Bright Data
  • From plain httpx / requests
• Troubleshooting
  • tierproxy doctor first
  • 401 Unauthorized
  • 403 Forbidden on a specific country
  • Slow first request
  • Connection timeouts
  • global is not defined (in browser bundlers)
  • MCP server doesn’t show in Claude Desktop
  • “BudgetExceededError”
  • OTel spans not showing up
• API Reference
  • Client
  • Resources
  • Proxy URL builder & selector
  • Retry policy
  • Exceptions

Install

pip install tierproxy

Optional extras:

pip install "tierproxy[requests]"   # adapter for the `requests` library
pip install "tierproxy[docs]"       # build the documentation locally

At a glance

from tierproxy import TierProxy

with TierProxy() as client:
    me = client.me.get()
    print(me.client_id, me.used_bytes_month, "of", me.quota_bytes_month)

The SDK supports both synchronous (TierProxy) and asynchronous (AsyncTierProxy) usage, exposes a typed exception hierarchy, includes a configurable retry policy with exponential backoff + jitter, and streams live usage deltas via Server-Sent Events.

See the Quickstart for a 5-minute walkthrough and the API reference for the complete public surface.

Performance

ProxyURL builds in well under 1 µs (basic), ~2 µs with full modifiers. The smart pick selector chooses from 100 upstreams in ~17 µs, 1000 upstreams in ~60 µs. See benchmarks.

Indices

• Index

• Module Index

• Search Page