The official Python SDK for the ProxyHat residential proxy API.
Tip
Recommended proxies — ProxyHat residential IPs. Every feature in this package is tested end-to-end against ProxyHat and works great. First-class integration; also works with any proxy, or none.
- One-call proxy connection —
client.connection_url()turns your API key into a ready-to-use residential proxy URL - Full coverage of the ProxyHat API
- Local gateway URL builder (
build_connection_url) — no network needed - Sync (
ProxyHat) and async (AsyncProxyHat) clients - Typed responses using dataclasses
- Comprehensive error handling with typed exceptions
- Pagination support for location endpoints
pip install proxyhatfromproxyhatimportProxyHatclient=ProxyHat(api_key="ph_your_api_key")
# List sub-usersusers=client.sub_users.list()
foruserinusers:
print(user.proxy_username, user.lifecycle_status)
# Create a sub-usernew_user=client.sub_users.create(
proxy_password="secure_pass",
is_traffic_limited=True,
traffic_limit="5GB",
name="Scraper",
)
print(new_user.uuid)importasynciofromproxyhatimportAsyncProxyHatasyncdefmain():
asyncwithAsyncProxyHat(api_key="ph_your_api_key") asclient:
users=awaitclient.sub_users.list()
foruserinusers:
print(user.proxy_username)
asyncio.run(main())From an API key to actually routing traffic in one call — the SDK looks up an active sub-user and builds the gateway URL for you:
fromproxyhatimportProxyHatproxy=ProxyHat(api_key="ph_your_api_key")
# Rotating residential IP, US exit:url=proxy.connection_url(country="us")
# → http://<user>-country-us:<pass>@gate.proxyhat.com:8080# Sticky session (same IP for 30m), city-targeted, SOCKS5:sticky=proxy.connection_url(country="de", city="berlin", sticky="30m", protocol="socks5")
# Use it with any HTTP client:importhttpxresp=httpx.get("https://api.ipify.org", proxy=url)Offline builder — if you already have a sub-user's credentials, build the URL with no network call:
fromproxyhatimportbuild_connection_urlurl=build_connection_url(username="ph-8f2a1c", password="PxSecret123", country="gb", filter="high")Server-built descriptor — let the API assemble it (validates the sub-user is active):
d=proxy.proxy_descriptors.create(
sub_user_uuid=user.uuid,
protocol="http",
location={"country": "us", "city": "new_york"},
session={"mode": "sticky", "ttl": "30m"},
)
print(d.url)Get your API key from the ProxyHat Dashboard.
See the Authentication Guide for details.
| Resource | Methods |
|---|---|
client.auth | register, login, user, logout, supported_providers, social_accounts, disconnect_social, oauth_redirect |
client.sub_users | list, create, get, update, delete, reset_usage, bulk_delete, bulk_move_to_group |
client.sub_user_groups | list, create, get, update, delete |
client.locations | countries, regions, cities, isps, zipcodes |
client.analytics | traffic, traffic_total, requests, requests_total, domain_breakdown |
client.proxy_presets | list, create, get, update, delete |
client.proxy_descriptors | create |
client.connection_url(...) | build a ready proxy URL from an active sub-user |
client.profile | get_preferences, update_preferences, list_api_keys, create_api_key, delete_api_key, regenerate_api_key |
client.two_factor | status, enable, confirm, disable, qr_code, recovery_codes, disable_by_recovery, change_password |
client.email | request_change, confirm_change, cancel_change, resend_verification |
client.coupons | validate, apply, redeem |
client.plans | list_regular, list_subscriptions, get_regular, get_subscription, pricing_regular, pricing_subscriptions |
client.payments | list, create, get, check, invoice, cryptocurrencies |
fromproxyhatimportProxyHat, ProxyHatError, NotFoundError, RateLimitError, ValidationErrorclient=ProxyHat(api_key="ph_your_api_key")
try:
user=client.sub_users.get("nonexistent-id")
exceptNotFoundErrorase:
print(f"Not found: {e.message}")
exceptRateLimitErrorase:
print(f"Rate limited. Retry after {e.retry_after}s")
exceptValidationErrorase:
print(f"Validation failed: {e.errors}")
exceptProxyHatErrorase:
print(f"API error {e.status_code}: {e.message}")See the Error Handling Guide for the full list of error codes.
- ProxyHat — Residential & mobile proxy network
- Dashboard — Manage proxies, sub-users, and API keys
- GitHub — Source code & issue tracker
MIT — see LICENSE for details.