ProxyHat Python SDK

The official Python SDK for the ProxyHat residential proxy API.

Features

• Full coverage of the ProxyHat API
• Sync (ProxyHat) and async (AsyncProxyHat) clients
• Typed responses using dataclasses
• Comprehensive error handling with typed exceptions
• Pagination support for location endpoints

Installation

pip install proxyhat

Quick Start

from proxyhat import ProxyHat

client = ProxyHat(api_key="ph_your_api_key")

# List sub-users
users = client.sub_users.list()
for user in users:
    print(user.proxy_username, user.lifecycle_status)

# Create a sub-user
new_user = client.sub_users.create(
    proxy_password="secure_pass",
    is_traffic_limited=True,
    traffic_limit="5GB",
    name="Scraper",
)
print(new_user.uuid)

Async Usage

import asyncio
from proxyhat import AsyncProxyHat

async def main():
    async with AsyncProxyHat(api_key="ph_your_api_key") as client:
        users = await client.sub_users.list()
        for user in users:
            print(user.proxy_username)

asyncio.run(main())

Authentication

Get your API key from the ProxyHat Dashboard.

See the Authentication Guide for details.

API Reference

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.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

Error Handling

from proxyhat import ProxyHat, ProxyHatError, NotFoundError, RateLimitError, ValidationError

client = ProxyHat(api_key="ph_your_api_key")

try:
    user = client.sub_users.get("nonexistent-id")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Validation failed: {e.errors}")
except ProxyHatError as e:
    print(f"API error {e.status_code}: {e.message}")

See the Error Handling Guide for the full list of error codes.

Documentation

• Getting Started
• API Reference
• Full Documentation

Links

• ProxyHat — Residential & mobile proxy network
• Dashboard — Manage proxies, sub-users, and API keys
• GitHub — Source code & issue tracker

License

MIT — see LICENSE for details.