Webshare Python SDK reference Every public method, grouped by resource. All methods exist on both the
synchronous Webshare client and the asynchronous AsyncWebshare client with
identical signatures — on the async client, await the call (and use
async for to iterate pages). Every method additionally accepts the
per-request options timeout, headers, max_retries, subuser_id and
federated_user_id.
Most operations accept plan_id to target a specific plan; get plan IDs from
client.plans.list() and pass one explicitly (an account default is used
when omitted).
webshare .Webshare (...) # synchronous client
webshare .AsyncWebshare (...) # asynchronous client (same options) Constructor options: api_key (falls back to WEBSHARE_API_KEY),
credentials_provider (callable returning the token; async client also
accepts async callables), base_url (default https://proxy.webshare.io),
timeout (seconds per attempt, default 60), max_retries (default 2),
http_client (inject an httpx.Client/httpx.AsyncClient),
default_headers, subuser_id, federated_user_id,
retry_non_idempotent (opt POST/PATCH into retries),
unauthenticated (credential-free client for unauthenticated endpoints).
Pagination
list methods return SyncPage[T] / AsyncPage[T] exposing .results,
.count, .next, .previous and .next_page(); iterating the page object
(for x in page / async for x in page) yields items across all pages.
All errors derive from webshare.WebshareError. API failures raise a
status-specific subclass of webshare.APIError (attributes: status_code,
code, request_id, detail, field_errors, body, retry_after):
BadRequestError (400), AuthenticationError (401), PermissionDeniedError
(403), NotFoundError (404), RateLimitError (429), InternalServerError
(5xx). Undecodable 2xx bodies raise ResponseDecodeError; transport failures
raise APIConnectionError / APITimeoutError.
Function
Description
webshare.build_proxy_url(mode=..., username=..., password=..., country_codes=..., city=..., session_id=..., rotate=...)Build a proxy connection URL (backbone username grammar or direct mode; IP-auth mode when credentials are omitted).
webshare.build_proxy_list_download_url(token, country_codes=..., endpoint_mode=..., plan_id=...)Build the unauthenticated proxy list download URL from a download token.
Method
Description
Docs
client.proxies.list(mode=..., plan_id=..., page=..., page_size=..., country_code__in=..., ...)List proxies (paginated; mode is required).
docs
client.proxies.refresh(plan_id=...)Refresh the entire proxy list (uses an on-demand refresh).
docs
client.proxies.download(token, country_codes=..., endpoint_mode=..., plan_id=...)Download the proxy list as text, one address:port:username:password line per proxy.
docs
client.proxies.download_url(token, country_codes=..., endpoint_mode=..., plan_id=...)Build the download URL without calling it.
docs
Method
Description
Docs
client.proxy_config.get(plan_id=...)Get the proxy config (v3; plan_id required).
docs
client.proxy_config.get_stats(plan_id=...)Get proxy list composition stats: countries, IP ranges, ASNs (v3).
docs
client.proxy_config.get_status(plan_id=...)Get proxy list readiness state and credentials (v3).
docs
client.proxy_config.update(plan_id=..., username=..., password=..., ...)Partially update the proxy config.
docs
client.proxy_config.allocate_unallocated_countries(new_countries=..., plan_id=...)Allocate proxies stuck in unallocated_countries.
docs
client.proxy_replacements
Method
Description
Docs
client.proxy_replacements.list(plan_id=..., state=..., dry_run=...)List proxy replacements (paginated).
docs
client.proxy_replacements.create(to_replace=..., replace_with=..., dry_run=..., plan_id=...)Create an asynchronous proxy replacement; poll get until completed.
docs
client.proxy_replacements.get(id, plan_id=...)Get a proxy replacement (poll after create).
docs
Method
Description
Docs
client.replaced_proxies.list(proxy_list_replacement=..., plan_id=...)List replaced proxies (paginated).
docs
client.replaced_proxies.download(download_token=..., country_codes=..., mode=...)Download the replaced proxy list as text (token scope replaced_proxy).
docs
Method
Description
Docs
client.stats.list(timestamp__gte=..., timestamp__lte=..., plan_id=...)List hourly proxy usage stats (bare array, not paginated).
docs
client.stats.aggregate(timestamp__gte=..., timestamp__lte=..., plan_id=...)Aggregate proxy usage stats for a period.
docs
Method
Description
Docs
client.proxy_activity.list(starting_after=..., page_size=..., plan_id=..., ...)List proxy activity (paginated via starting_after).
docs
client.proxy_activity.download(download_token=..., plan_id=..., ...)Download proxy activities as CSV text (token scope activity).
docs
Method
Description
Docs
client.download_tokens.get(scope)Get a download token (proxy_list, replaced_proxy or activity).
docs
client.download_tokens.reset(scope)Reset (rotate) the download token for a scope.
docs
Method
Description
Docs
client.ip_authorizations.list(plan_id=...)List IP authorizations (paginated).
docs
client.ip_authorizations.create(ip_address=..., plan_id=...)Authorize an IP address.
docs
client.ip_authorizations.get(id, plan_id=...)Get an IP authorization.
docs
client.ip_authorizations.delete(id, plan_id=...)Delete an IP authorization.
docs
client.ip_authorizations.whats_my_ip()Return your public IP address.
docs
Method
Description
Docs
client.subusers.list(plan_id=...)List sub-users (paginated).
docs
client.subusers.create(label=..., proxy_limit=..., max_thread_count=..., plan_id=...)Create a sub-user.
docs
client.subusers.get(id, plan_id=...)Get a sub-user.
docs
client.subusers.update(id, label=..., plan_id=..., ...)Partially update a sub-user.
docs
client.subusers.delete(id, plan_id=...)Delete a sub-user.
docs
client.subusers.refresh_proxy_list(id)Refresh a sub-user's custom proxy list.
docs
Method
Description
Docs
client.profile.get()Retrieve the user profile.
docs
client.profile.update(first_name=..., timezone=..., ...)Partially update the user profile.
docs
client.profile.get_preferences()Retrieve the user preferences.
docs
client.profile.update_preferences(...)Update the user preferences.
docs
Method
Description
Docs
client.notifications.list(dismissed_at__isnull=..., type=...)List account notifications (paginated).
docs
client.notifications.get(id)Get a notification.
docs
client.notifications.dismiss(id)Dismiss a notification.
docs
client.notifications.restore(id)Restore a dismissed notification.
docs
Method
Description
Docs
client.id_verification.get()Get the ID verification object (Stripe Identity).
docs
Method
Description
Docs
client.verification.flows.list()List account verification flows (paginated).
docs
client.verification.flows.get(id)Get a verification flow.
docs
client.verification.flows.submit_evidence(id, explanation=..., files=...)Submit evidence (multipart; accepts paths, bytes or file objects).
docs
client.verification.flows.submit_security_code(id, security_code=...)Submit the bank-statement security code.
docs
client.verification.questions.list(flow__type=..., answer__isnull=..., ...)List compliance questions (paginated).
docs
client.verification.questions.submit_answer(question_id, answer=..., files=...)Submit an answer with optional attachments (multipart).
docs
client.verification.appeals.list(state=...)List suspension appeals (paginated).
docs
client.verification.appeals.create(appeal=...)Submit a suspension appeal.
docs
client.verification.abuse_reports.list()List abuse reports (paginated).
docs
client.verification.get_suspension()Get suspension details (works while suspended).
docs
client.verification.get_categories()Get verification categories (map keyed by category).
docs
client.verification.get_limits()Get the current verification limits.
docs
client.verification.get_thresholds()Get verification thresholds (map keyed by category).
docs
Method
Description
Docs
client.billing.get_info()Get the billing information singleton.
docs
client.billing.update_info(name=..., address=..., billing_email=...)Update the billing information.
docs
Method
Description
Docs
client.payment_methods.list()List payment methods (paginated; polymorphic on type).
docs
client.payment_methods.get(id)Get a payment method.
docs
Method
Description
Docs
client.pending_payments.list()List pending payments (paginated).
docs
client.pending_payments.get(id)Get a pending payment (poll after a Stripe confirm).
docs
Method
Description
Docs
client.transactions.list()List transactions (paginated).
docs
client.transactions.get(id)Get a transaction.
docs
Method
Description
Docs
client.subscription.get()Get the subscription singleton.
docs
client.subscription.get_available_assets()Get available assets per proxy category/subtype.
docs
client.subscription.customize(proxy_type=..., proxy_countries=..., plan_id=...)Get customization limits/options for a plan configuration.
docs
client.subscription.pricing(proxy_type=..., proxy_countries=..., term=..., ...)Get the pricing for a custom plan configuration.
docs
client.subscription.enable_auto_renewal()Enable auto-renewal (payment method must be on file).
docs
client.subscription.cancel_auto_renewal()Cancel auto-renewal (also removes the payment method).
docs
Method
Description
Docs
client.plans.list()List all plans, including non-active ones (paginated).
docs
client.plans.get(id)Get a plan.
docs
client.plans.update(id, automatic_refresh_next_at=...)Update a plan (only automatic_refresh_next_at is editable).
docs
client.plans.cancel(id)Cancel a plan (subscription credited for the remainder).
docs
Method
Description
Docs
client.invoices.download(subscription_transaction_id=...)Download an invoice as PDF bytes.
docs
Method
Description
Docs
client.referral.get_config()Get the referral config.
docs
client.referral.update_config(mode=..., paypal_payout_email=...)Update the referral config.
docs
client.referral.get_coupon_code()Get the currently applied coupon code.
docs
client.referral.apply_coupon_code(code=...)Apply a coupon code (5/min rate limit).
docs
client.referral.remove_coupon_code()Remove the applied coupon code.
docs
client.referral.list_channels()List referral channels (bare array, not paginated).
docs
client.referral.list_credits(mode=..., status=..., ordering=...)List referral credits (paginated).
docs
client.referral.get_credit(id)Get a referral credit.
docs
client.referral.list_earnouts()List earn outs (paginated).
docs
client.referral.get_earnout(id)Get an earn out.
docs
client.referral.get_code_info(referral_code=...)Get public referral code info (unauthenticated).
docs