{
  "markdown": "# tierproxy — Python SDK\n\n<!-- mcp-name: io.github.tierproxy/python-sdk -->\n\n> 🚧 **Preview release.** Gateway is not yet generally available. Join the\n> waitlist at hello@tierproxy.com. SDK is functional but `tierproxy doctor`\n> against a live gateway requires invitation.\n\n[![PyPI version](https://img.shields.io/pypi/v/tierproxy.svg?logo=python&logoColor=white)](https://pypi.org/project/tierproxy/)\n[![Python versions](https://img.shields.io/pypi/pyversions/tierproxy.svg)](https://pypi.org/project/tierproxy/)\n[![Downloads](https://static.pepy.tech/badge/tierproxy/month)](https://pepy.tech/project/tierproxy)\n[![CI](https://github.com/tierproxy/python-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/tierproxy/python-sdk/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/tierproxy/python-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/tierproxy/python-sdk)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![OpenAPI 3.1](https://img.shields.io/badge/OpenAPI-3.1-6BA539?logo=openapiinitiative)](https://github.com/tierproxy/python-sdk/blob/main/openapi/tierproxy.v1.yaml)\n[![MCP compatible](https://img.shields.io/badge/MCP-compatible-blueviolet?logo=anthropic)](#mcp-server-claude-desktop--cursor--cline--windsurf)\n\nPremium multi-provider proxy infrastructure for AI/ML pipelines. Built for engineers who measure cost, latency, and success rate twice — and write Python.\n\n## Install\n\n```bash\npip install tierproxy\n```\n\n## Quickstart — five-second flavor\n\n```python\nimport tierproxy\nr = tierproxy.get(\"https://example.com\", country=\"US\")\nprint(r.text)\n```\n\nThat's it. (Set `TIERPROXY_API_KEY` env var first.)\n\n## Three lines, persistent session\n\n```python\nfrom tierproxy import TierProxy\nwith TierProxy() as g:\n    print(g.me.get().client_id)\n    r = g.get(\"https://example.com\", country=\"US\", session_id=\"s1\")\n```\n\n## Auto-pick the cheapest healthy upstream every request\n\n```python\ng = TierProxy(routing=\"cheapest\")  # also: \"fastest\", \"most_reliable\", \"balanced\"\ng.get(\"https://example.com\")     # picks via /v1/health/upstreams under the hood\n```\n\n## Cost guardrails\n\n```python\ng = TierProxy(\n    monthly_budget_usd=200.0,    # raises BudgetExceededError before going over\n)\n```\n\n## Power-user knobs\n\n```python\nimport httpx\nfrom tierproxy import TierProxy\nfrom tierproxy.retry import RetryPolicy\n\ng = TierProxy(\n    api_key=\"tp_live_...\",\n    base_url=\"https://my-self-hosted-gw:8444\",\n    timeout=10.0,\n    retry_policy=RetryPolicy(max_retries=5, retry_on_status=frozenset({500, 502})),\n    http_client=httpx.Client(verify=False),  # custom transport\n    user_agent_suffix=\"my-app/2.3\",          # attribution\n)\n```\n\n## Raw modes (Playwright, curl, etc.)\n\n```python\nfrom tierproxy import ProxyURL\n\np = ProxyURL(api_key=\"tp_live_...\", country=\"US\", mode=\"username_encoding\")\nprint(p.http_url())  # http://customer-tp_live_...-cc-US:x@gw.tierproxy.com:443\n```\n\n## Error handling\n\nEvery SDK error inherits from `tierproxy.TierProxyError` and carries a\n`request_id` for support escalation:\n\n```python\nfrom tierproxy import TierProxy, RateLimitError\nimport time\n\nwith TierProxy() as g:\n    try:\n        resp = g.get(\"https://example.com/page\")\n    except RateLimitError as e:\n        time.sleep(e.retry_after or 5)\n        resp = g.get(\"https://example.com/page\")\n```\n\nSee [Errors reference](https://python.tierproxy.com/errors.html) for the\nfull HTTP-status-to-exception mapping.\n\n## AI agent integration\n\nThe SDK exposes its response models as JSON Schema and as pre-built tool\ndefinitions for Anthropic Claude and OpenAI function-calling:\n\n```python\nimport anthropic\nfrom tierproxy import TierProxy, schemas\n\nwith TierProxy() as gw:\n    anthropic.Anthropic().messages.create(\n        model=\"claude-sonnet-4-6\",\n        max_tokens=1024,\n        tools=schemas.anthropic_tools(),\n        messages=[{\"role\": \"user\", \"content\": \"How much quota is left?\"}],\n    )\n```\n\nSee the [AI integration guide](https://python.tierproxy.com/ai-integration.html)\nand the MCP server in\n[`examples/mcp_claude_desktop.md`](examples/mcp_claude_desktop.md).\n\n## How tierproxy compares\n\n| | tierproxy | Smartproxy SDK | Bright Data SDK | Oxylabs SDK | DataImpulse |\n|---|---|---|---|---|---|\n| Multi-provider routing | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Client-side smart selector (cost-aware) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Live usage streaming (SSE) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| MCP server (Claude/Cursor/Cline) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| OpenTelemetry built-in | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Sync + async parity | ✅ | partial | partial | partial | partial |\n| AI/ML framework examples shipped | 8 | 0 | 1 | 0 | 0 |\n| Type-safe (Pydantic v2 + mypy strict) | ✅ | ❌ | ❌ | partial | ❌ |\n| OpenAPI 3.1 spec | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Pip-installable CLI (`tierproxy doctor`) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Per-request cost attribution (lazy) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| JA3/JA4 TLS fingerprint rotation | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Rate-limit learning + auto-failover | ✅ | ❌ | ❌ | ❌ | ❌ |\n| License | Apache 2.0 | proprietary | proprietary | proprietary | proprietary |\n\n## Features\n\n- **Five-second quickstart** — `import tierproxy; tierproxy.get(url, country=\"US\")`\n- **Layered API** — five integration levels from one-liner to power-user knobs\n- **Smart routing** — `routing=\"cheapest\"` auto-picks healthy upstream per request\n- **Cost guardrails** — `monthly_budget_usd=` refuses requests that would exceed budget\n- **Per-request cost attribution** — `client.cost_for(resp)` returns USD; lazy 30s cache, no per-request overhead\n- **Client-side response caching** — `cache_ttl=300, cache_max_response_size=262144` LRU with size cap\n- **Multi-provider auto-failover** — `auto_failover=True` retries with next-best upstream on 429/5xx\n- **Rate-limit learning** — `client.rate_limits.get()` surfaces gateway-aggregated 429s per target domain\n- **JA3/JA4 TLS rotation** — per-upstream fingerprint randomization (gateway side; see [tls-fingerprint guide](docs/tls-fingerprint.md))\n- **Cookie persistence** — cookies stick to `session_id` across multi-step crawls\n- **Streaming responses** — `client.get(url, stream=True)` returns iterator (large files, SSE)\n- **Live SSE stream** — `for delta in g.usage.stream()` tails month-to-date bytes\n- **MCP server** — `tierproxy-mcp` exposes proxy as tools to Claude/Cursor/Cline\n- **8 framework integrations** — LangChain, LlamaIndex, Crawl4AI, Playwright, Firecrawl, Browser-Use, CrewAI\n- **OpenTelemetry opt-in** — `pip install tierproxy[otel]` for distributed tracing\n- **Geo + sticky sessions** — countries, cities, 1-1440min session pins\n- **Dual URL syntax** — headers (httpx/requests) AND username-encoding (Playwright)\n- **Type-safe end-to-end** — Pydantic v2 models, mypy strict, full IDE autocomplete\n\nSee [examples/](./examples) for LangChain/LlamaIndex/Crawl4AI/Playwright and\n[`examples/levels.py`](./examples/levels.py) for a runnable demo of every level.\n\n## Use with your favorite AI/agent framework\n\n| Framework | Example | Notes |\n|---|---|---|\n| **LangChain** | [`with_langchain.py`](./examples/with_langchain.py) | RAG document loaders through proxy |\n| **LlamaIndex** | [`with_llamaindex.py`](./examples/with_llamaindex.py) | SimpleWebPageReader through proxy |\n| **Crawl4AI** | [`with_crawl4ai.py`](./examples/with_crawl4ai.py) | Playwright crawler + tierproxy |\n| **Firecrawl** (hot) | [`with_firecrawl.py`](./examples/with_firecrawl.py) | Self-hosted Firecrawl + residential IPs |\n| **Browser-Use** (hot) | [`with_browser_use.py`](./examples/with_browser_use.py) | LLM-driven autonomous browser |\n| **CrewAI** (hot) | [`with_crewai.py`](./examples/with_crewai.py) | Multi-agent scraper crew + cost-aware routing |\n| **Playwright** | [`with_playwright.py`](./examples/with_playwright.py) | Direct Playwright with tierproxy |\n| **MCP (Claude/Cursor/Cline/Windsurf)** (unique) | [`mcp_claude_desktop.md`](./examples/mcp_claude_desktop.md) | Native tool integration via `tierproxy-mcp` |\n\n## MCP server (Claude Desktop / Cursor / Cline / Windsurf)\n\n```bash\npip install tierproxy[mcp]\n```\n\nThen add to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"tierproxy\": {\n      \"command\": \"tierproxy-mcp\",\n      \"env\": { \"TIERPROXY_API_KEY\": \"tp_live_...\" }\n    }\n  }\n}\n```\n\nNow your AI assistant can call `fetch_url(url, country=\"US\")`, inspect health\nand usage, and route through the cheapest healthy upstream — no glue code,\nno httpx imports, no boilerplate.\n",
  "bytes": 8465,
  "sha": "aeab8370aff264131fb3357db01e37757b386012693f081a85f2647fb5977b72",
  "repo_slug": "tierproxy/python-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tierproxy_python_sdk_93d88fc0/readme"
}