NAV Navbar
python shell

Introduction

The Webshare API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Webshare API supports backwards compatibility. Any API changes always are backwards compatible.

We have language bindings in Shell and HTTP! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

Authenticated Request Example

import requests

requests.get("https://proxy.webshare.io/api/profile/", headers={"Authorization": "Token APIKEY"})

# With shell, you can just pass the correct header with each request
curl "https://proxy.webshare.io/api/profile/" \
  -H "Authorization: Token APIKEY"

Make sure to replace APIKEY with your API key.

Webshare uses API keys to allow access to the API. You can register a new Webshare API key at our API keys page.

Webshare expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token APIKEY

User Profile

The user profile object

You can use the API to retrieve information about your Webshare user profile.

The user profile object

{  
  "email": "user@webshare.io",
  "full_name": "First Last Name",
  "date_joined": "2019-06-09T23:34:00.095501-07:00",
  "last_login": "2019-06-09T23:34:00.095501-07:00"
}

User Profile Object

Attributes Description
email Email for the Webshare account
full_name Full name of the user. May be empty string. The name is retrieved from Google Auth.
date_joined Registration time of the Webshare account.
last_login Last login time of the Webshare account. The API requests do not modify the last_login field.

Get user profile

This endpoint retrieves the user profile.

import requests

response = requests.get("https://proxy.webshare.io/api/profile/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/profile/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
  "email": "user@webshare.io",
  "full_name": "First Last Name",
  "date_joined": "2019-06-09T23:34:00.095501-07:00",
  "last_login": "2019-06-09T23:34:00.095501-07:00"
}

HTTP Request

GET https://proxy.webshare.io/api/profile/

Subscription

The subscription object

You can use the API to retrieve information about your subscription.

The subscription object

{  
  "proxy_type": "cloud",
  "proxy_count": 105,
  "countries": {"US":5, "FR":100},
  "bandwidth_limit": 268435456000,

  "automatic_refresh_frequency": 3600,
  "ondemand_refreshes_total": 1,
  "proxy_replacements_total": 1,

  "unlimited_ip_authorizations": true,
  "unlimited_burst_threads": true,

  "start_date": "2019-05-09T23:34:00.095501-07:00",
  "end_date": "2019-06-09T23:34:00.095501-07:00",
  "renewals_paid": 0,

  "monthly_price": 29.99,
  "yearly_price": 299.99,
  "free_credits": 10.00,

  "subuser_count": 3
}

Subscription Object

Attributes Description
proxy_type Proxy types could be free,cloud, premiumcloud or dedicated.
proxy_count Number of proxies in the proxy subscription.
countries Number of proxies from each country code. ZZ means country will is randomly allocated.
bandwidth_limit The proxy bandwidth limit in bytes. 0 means unlimited.
automatic_refresh_frequency Auto-refresh your proxy list every automatic_refresh_frequency seconds. 0 value means no automatic refreshes.
on_demand_refreshes_total On-demand proxy list refreshes you are subscribed to.
proxy_replacements_total Individual proxy replacements you are subscribed to.
unlimited_ip_authorizations If true subscription supports unlimited IP Authorizations. If false, only 1 IP Authorization is supported.
unlimited_burst_threads If true subscription supports up to 2,000 concurrent proxy requests. If false, 500 concurrent proxy requests are supported.
start_date The start date of the subscription.
end_date The end date of the subscription. The bandwidth will reset on this date.
renewals_paid Number of subscription renewals paid. Each renewal corresponds to a month. If renewals_paid is 0, you will be charged monthly_price to renew your subscription.
monthly_price Monthly price of the subscription in USD.
yearly_price Yearly price of the subscription in USD.
free_credits Free credits available in your account in USD.
subuser_count Number of sub-users available in your subscription.

Get subscription

This endpoint retrieves the subscription object

import requests

response = requests.get("https://proxy.webshare.io/api/subscription/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/subscription/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
  "proxy_type": "cloud",
  "proxy_count": 105,
  "countries": {"US":5, "FR":100},
  "bandwidth_limit": 268435456000,

  "rotate_frequency": 3600,
  "rotate_percentage": 100,
  "last_rotate_at": "2019-05-09T23:34:00.095501-07:00",
  "next_rotate_at": "2019-05-10T23:34:00.095501-07:00",

  "proxy_list_rotate_on_demand": 1,
  "proxy_list_rotate_on_demand_used": 1,
  "proxy_list_rotate_on_demand_available": 0,

  "unlimited_ip_authorizations": true,
  "unlimited_burst_threads": true,

  "start_date": "2019-05-09T23:34:00.095501-07:00",
  "end_date": "2019-06-09T23:34:00.095501-07:00",
  "renewals_paid": 0,

  "monthly_price": 29.99,
  "yearly_price": 299.99,
  "free_credits": 10.00,

  "subuser_count": 3
}

HTTP Request

GET https://proxy.webshare.io/api/subscription/

Proxy Configuration

The proxy config object

You can use the API to retrieve information about your proxy configuration.

The proxy config object

{
  "countries": {"US":5, "FR":100},
  "username": "hasdyas",
  "password": "jasdi2148",
  "authorized_ips": ["10.2.5.10", "10.2.6.10"],
  "download_links": {
    "http_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/domain/",
    "http_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/direct/",
    "http_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/domain/",
    "http_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/direct/",
    "socks5_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/domain/",
    "socks5_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/direct/",
    "socks5_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/domain/",
    "socks5_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/direct/"
  }
}

Proxy Config Object

Attributes Description
countries Dictionary of proxy counts by country code.
username Username of the proxy.
password Password of the proxy.
authorized_ips List of IP addresses. IPs authorized to make requests to Webshare Proxy. authorized_ips is used only if not using username/password.
download_links List of links to download your proxy list. You can use these links to download your proxy list without authentication.

Get proxy config

This endpoint retrieves the proxy config.

import requests

response = requests.get("https://proxy.webshare.io/api/proxy/config/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/proxy/config/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
  "countries": {"US":5, "FR":100},
  "username": "hasdyas",
  "password": "jasdi2148",
  "authorized_ips": ["10.2.5.10", "10.2.6.10"],
  "download_links": {
    "http_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/domain/",
    "http_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/direct/",
    "http_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/domain/",
    "http_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/direct/",
    "socks5_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/domain/",
    "socks5_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/direct/",
    "socks5_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/domain/",
    "socks5_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/direct/"
  }
}

HTTP Request

GET https://proxy.webshare.io/api/proxy/config/

Update proxy config

This endpoint updates the proxy config.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/proxy/config/",
    json={"authorized_ips":["10.3.5.10"]},  
    headers={"Authorization": "Token APIKEY"}
)
response.json()

curl "https://proxy.webshare.io/api/proxy/config/" \
  -X POST \
  -d "{\"authorized_ips\": [\"10.3.5.10\"]}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
  "countries": {"US":5, "FR":100},
  "username": "hasdyas",
  "password": "newpassword",
  "authorized_ips": ["10.3.5.10"],
  "download_links": {
    "http_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/domain/",
    "http_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/direct/",
    "http_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/domain/",
    "http_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/direct/",
    "socks5_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/domain/",
    "socks5_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/direct/",
    "socks5_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/domain/",
    "socks5_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/direct/"
  }
}

HTTP Request

POST https://proxy.webshare.io/api/proxy/config/

Request Body

Parameter Description
authorized_ips The new list of authorized IPs.

Reset proxy password

This endpoint resets the proxy password.

import requests

response = requests.post("https://proxy.webshare.io/api/proxy/config/reset_password/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/proxy/config/reset_password/" \
  -X POST \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
  "countries": {"US":5, "FR":100},
  "username": "hasdyas",
  "password": "newpassword",
  "authorized_ips": ["10.2.5.10", "10.2.6.10"],
  "download_links": {
    "http_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/domain/",
    "http_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/username/direct/",
    "http_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/domain/",
    "http_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/http/port/direct/",
    "socks5_password_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/domain/",
    "socks5_password_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/username/direct/",
    "socks5_ip_backbone": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/domain/",
    "socks5_ip_direct": "/proxy/list/download/uniquelongtokenforthisuser/-/socks/port/direct/"
  }
}

HTTP Request

POST https://proxy.webshare.io/api/proxy/config/reset_password/

Proxy List

The proxy list object

You can use the API to retrieve information about your proxy list.

The proxy list object

{  
  "username": "hasdyas-dest",
  "password": "jasdi2148",
  "proxy_address": "193.8.94.149",
  "ports": {"http":8167, "socks5":8168},
  "valid": true,
  "last_verification": "2019-06-09T23:34:00.095501-07:00",
  "country_code": "US",
  "country_code_confidence": 0.95,
  "city_name": "New York"
}

Note: This API is paginated and returns multiple proxy list objects.

Proxy List Object

Attributes Description
username Full proxy username.
password Proxy password.
proxy_address Assigned IP address of the proxy. Do not connect to this address unless you are using Direct Connection option.
valid If the proxy is working as expected. Webshare checks proxies once every minute to make sure they are valid.
last_verification Last time the proxy checker was run on this proxy.
ports Dictionary of ports by proxy protocol. Used for IP Authorization requests only.
country_code The country code of the proxy.
country_code_confidence The country code confidence of the proxy. Must be a number between 0 to 1.
city_name The city name of the proxy.

List proxies

This endpoint lists the proxies.

import requests

response = requests.get("https://proxy.webshare.io/api/proxy/list/?page=1&countries=US-FR", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/proxy/list/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
    "count": 1000,
    "next": "https://proxy.webshare.io/api/proxy/list/?page=2",
    "previous": null,
    "results": [
        {  
          "username": "hasdyas-dest",
          "password": "jasdi2148",
          "proxy_address": "193.8.94.149",
          "ports": {"http":8167, "socks5":8168},
          "valid": true,
          "last_verification": "2019-06-09T23:34:00.095501-07:00",
          "country_code": "US",
          "country_code_confidence": 0.95,
          "city_name": "New York"
        },
        ...
    ]
}

HTTP Request

GET https://proxy.webshare.io/api/proxy/list/

URL Parameters

Parameter Description
page The current page for the proxies. Optional. Defaults to 1.
countries Filter proxies using - separated country codes. Optional. Defaults to all countries. E.g. US, US-FR, US-FR-JP-DE

Proxy Replacements

You can replace your proxies using 3 different methods:

  1. Auto-refresh your proxy list periodically (e.g. refresh once a day).
  2. On-demand refresh your proxy list when you wish to.
  3. Replace individual proxies from your list as needed.

The replacement info object

You can use the API to retrieve information about your subscription.

The replacement info object

{
  "automatic_refresh_frequency": 3600,
  "automatic_refresh_percentage": 100,
  "automatic_refresh_last_at": "2019-05-09T23:34:00.095501-07:00",
  "automatic_refresh_next_at": "2019-05-10T23:34:00.095501-07:00",

  "ondemand_refreshes_total": 1,
  "ondemand_refreshes_used": 1,
  "ondemand_refreshes_available": 0,

  "proxy_replacements_total": 1,
  "proxy_replacements_used": 1,
  "proxy_replacements_available": 0,
}

Replacement Info Object

Attributes Description
automatic_refresh_frequency Auto-refresh your proxy list every automatic_refresh_frequency seconds. 0 value means no automatic refreshes.
automatic_refresh_percentage Auto-refresh your percentage of your proxy list every automatic_refresh_frequency seconds. 0 value means no automatic refreshes.
automatic_refresh_last_at Last time proxy list was auto-refreshed. May be set to null.
automatic_refresh_next_at Next time proxy list will be auto-refreshed. May be set to null.
on_demand_refreshes_total On-demand proxy list refreshes you are subscribed to.
on_demand_refreshes_used On-demand proxy list refreshes you have already used. Gets reset once a month.
on_demand_refreshes_available On-demand proxy list refreshes available.
proxy_replacements_total Individual proxy replacements you are subscribed to.
proxy_replacements_used Individual proxy replacements you have already used. Gets reset once a month.
proxy_replacements_available Individual proxy replacements available.

Get replacement info

This endpoint retrieves a specific user.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/proxy/replacement/info/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()

curl "https://proxy.webshare.io/api/proxy/replacement/info/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "automatic_refresh_frequency": 3600,
  "automatic_refresh_percentage": 100,
  "automatic_refresh_last_at": "2019-05-09T23:34:00.095501-07:00",
  "automatic_refresh_next_at": "2019-05-10T23:34:00.095501-07:00",

  "ondemand_refreshes_total": 1,
  "ondemand_refreshes_used": 1,
  "ondemand_refreshes_available": 0,

  "proxy_replacements_total": 1,
  "proxy_replacements_used": 1,
  "proxy_replacements_available": 0,
}

HTTP Request

GET https://proxy.webshare.io/api/proxy/replacement/info/

Refresh proxy list

Refresh your entire proxy list. You can only perform this action if you have ondemand_refreshes_available available.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/proxy/replacement/info/refresh/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()

curl "https://proxy.webshare.io/api/proxy/replacement/info/refresh/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
  "automatic_refresh_frequency": 3600,
  "automatic_refresh_percentage": 100,
  "automatic_refresh_last_at": "2019-05-09T23:34:00.095501-07:00",
  "automatic_refresh_next_at": "2019-05-10T23:34:00.095501-07:00",

  "ondemand_refreshes_total": 1,
  "ondemand_refreshes_used": 1,
  "ondemand_refreshes_available": 0,

  "proxy_replacements_total": 1,
  "proxy_replacements_used": 1,
  "proxy_replacements_available": 0,
}

HTTP Request

POST https://proxy.webshare.io/api/proxy/replacement/info/refresh/

List proxy replacements

This endpoint retrieves all previous proxy replacements 

import requests

response = requests.get("https://proxy.webshare.io/api/proxy/replacement/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/proxy/replacement/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

[  
  {  
     "ip_address": "10.100.50.2/32",
     "new_ip_address": "5.4.3.2",
     "created_at": "2019-06-09T23:34:00.095501-07:00"
  },
  ...
]

HTTP Request

GET https://proxy.webshare.io/api/proxy/replacement/

Proxy replacement Object

Attributes Description
ip_address The IP address replaced. May be presented in CIDR format (with / at the end). If CIDR is missing, assume /32.
new_ip_address The new IP address which was added to the proxy list.
created_at Read-only field to indicate when this IP was replaced.

Create proxy replacement

This endpoint lets you replace a specific proxy from your list.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/proxy/replacement/", 
    json={"ip_address": "10.100.50.2/32"},
    headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/proxy/replacement/" \
  -X POST \
  -d "{\"ip_address\": \"10.100.50.2/32\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "ip_address": "10.100.50.2/32",
   "new_ip_address": "5.4.3.2",
   "created_at": "2019-06-09T23:34:00.095501-07:00"
}

HTTP Request

POST https://proxy.webshare.io/api/proxy/replacement/

Proxy replacement Object

Attributes Description
ip_address The IP address replaced. May be presented in CIDR format (with / at the end). If CIDR is missing, assume /32.
created_at Read-only field to indicate when this IP was replaced.

Proxy Stats

The proxy stats object

You can use the API to retrieve information about your proxy statistics.

The proxy stats object

{  
  "bandwidth_used": 5368709120,
  "bandwidth_remaining": 48318382080,
  "bandwidth_limit": 53687091200,
  "bandwidth_projected": 59055800320,

  "last_request_at": "2019-06-09T23:34:00.095501-07:00",

  "requests_total": 5000,
  "requests_successful": 4999,
  "requests_failed": 1,
  "request_countries":{"US":4000, "FR":500, "GB":500},
  "requests_error_reasons":{"no_proxies_allocated": 1}
}

Proxy Stats Object

Attributes Description
bandwidth_used Proxy bandwidth used so far in bytes.
bandwidth_remaining Proxy bandwidth remaining in bytes. null if bandwidth limit is unlimited.
bandwidth_limit Proxy bandwidth limit. 0 if bandwidth limit is unlimited.
bandwidth_projected Projected bandwidth usage in bytes.
last_request_at The time of the last request. If no requests are sent, the value is null.
requests_total Number of proxy requests sent through Webshare Proxy.
requests_successful Number of successful proxy requests sent through Webshare Proxy.
requests_failed Number of failed proxy requests sent through Webshare Proxy.
request_countries Dictionary of proxy requests sent through Webshare Proxy by country code.
requests_error_reasons Dictionary of number of proxy request failure by error reason.

Get proxy stats

This endpoint retrieves the proxy stats.

import requests

response = requests.get("https://proxy.webshare.io/api/proxy/stats/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/proxy/stats/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
  "bandwidth_used": 5368709120,
  "bandwidth_remaining": 48318382080,
  "bandwidth_limit": 53687091200,
  "bandwidth_projected": 59055800320,

  "requests_total": 5000,
  "requests_countries":{"US":4000, "FR":500, "GB":500},
  "requests_successful": 4999,
  "requests_failed": 1,
  "request_failure_status_code":{"502": 1}
}

HTTP Request

GET https://proxy.webshare.io/api/proxy/stats/

Sub-users

Each sub-user can have separate limits and proxy list. The proxy list of the users you create are based on your main proxy list.

You can make requests to Proxy Configuration, Proxy List and Proxy Stats APIs as a sub-user using the X-Webshare-SubUser header. More examples below.

This API is only available for after accepting additional terms for Webshare sub-user portal. If you wish to gain access to this API, please complete the form at https://proxy.webshare.io/subuser/

The user object

You can use the API to create, retrieve, update and delete each individual user.

The user object

{  
   "id":7,
   "label":"Test User",
   "proxy_username":"eezocwls",
   "proxy_password":"r732w3h035mx",
   "proxy_countries": {
      "ZZ":1000
    },
   "proxy_limit":10.0,
   "proxy_usage":0,
   "max_thread_count": 500,
   "last_use":null,
   "created_at":"2019-06-09T23:34:00.095501-07:00",
   "updated_at":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_start_date":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_end_date":"2019-07-09T23:34:00.095517-07:00",
   "verification_status": "not_required"

}

User Object

Attributes Description
id Unique identifier of the user. The ID never changes and no other user will receive the same ID.
label You can set label to identify your users.
proxy_username The username to connect to the Webshare Proxy.
proxy_password The password to connect to the Webshare Proxy.
proxy_countries Can be set to null to disable custom proxy lists. Otherwise, dictionary of country code and number of proxies. ZZ country code is special and means any available country.
proxy_limit The user proxy limit in GBs. You can set to 0 in order to get unlimited bandwidth.
max_thread_count The maximum number of proxy request concurrency this user can have.
proxy_usage The proxy usage in bytes.
last_use ISO 8601 timestamp of the last time proxy was used. Example: 2019-06-10T01:49:10Z
created_at Read-only field to indicate when this user was created.
updated_at Read-only field to indicate when this user was last updated.
bandwidth_use_start_date The time we start calculating the user bandwidth use. You can edit this field.
bandwidth_use_end_date The time the user bandwidth use will reset. Read-only field.
verification_status The current account verification status of this user. See table below for detailed information.

Possible verification_status Fields

verification_status Description
not_required No account verification is required for this user.
in_progress Account verification is active for this user. Please check your email for further instructions.
verified This user is verified to use Webshare Proxy. Its unlikely that this user will be asked to verify again.
suspended This user was found to be not compatible with the Terms and Conditions of Webshare Proxy.

Create a user

Create a new user by setting label and bandwidth limit.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/subuser/",
    json={"label":"newcustomer", "proxy_limit": 10, "max_thread_count":500}, 
    headers={"Authorization": "Token APIKEY"}
)
response.json()

curl "https://proxy.webshare.io/api/subuser/" \
  -X POST \
  -d "{\"label\": \"newlabel\", \"proxy_limit\": 10, \"max_thread_count\":500}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "id":7,
   "label":"newcustomer",
   "proxy_username":"eezocwls",
   "proxy_password":"r732w3h035mx",
   "proxy_countries": null,
   "proxy_limit":10.0,
   "proxy_usage":0,
   "max_thread_count": 500,
   "last_use":null,
   "created_at":"2019-06-09T23:34:00.095501-07:00",
   "updated_at":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_start_date":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_end_date":"2019-07-09T23:34:00.095517-07:00"
}

HTTP Request

POST https://proxy.webshare.io/api/subuser/

Get a user

This endpoint retrieves a specific user.

import requests

response = requests.get("https://proxy.webshare.io/api/subuser/<ID>/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/subuser/<ID>/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "id":7,
   "label":"Test User",
   "proxy_username":"eezocwls",
   "proxy_password":"r732w3h035mx",
   "proxy_countries": null,
   "proxy_limit":10.0,
   "proxy_usage":0,
   "last_use":null,
   "created_at":"2019-06-09T23:34:00.095501-07:00",
   "updated_at":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_start_date":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_end_date":"2019-07-09T23:34:00.095517-07:00",
   "verification_status": "not_required"
}

HTTP Request

GET https://proxy.webshare.io/api/subuser/<ID>/

URL Parameters

Parameter Description
ID The ID of the user to retrieve

List users

This endpoint retrieves all users in the system. 

import requests

response = requests.get("https://proxy.webshare.io/api/subuser/", headers={"Authorization": "Token APIKEY"})
response.json()

curl "https://proxy.webshare.io/api/subuser/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "count":1,
   "next":null,
   "previous":null,
   "results":[  
      {  
         "id":7,
         "label":"Test User",
         "proxy_username":"eezocwls",
         "proxy_password":"r732w3h035mx",
         "proxy_countries": null,
         "proxy_limit":10.0,
         "proxy_usage":0,
         "last_use":null,
         "created_at":"2019-06-09T23:34:00.095501-07:00",
         "updated_at":"2019-06-09T23:34:00.095517-07:00",
         "bandwidth_use_start_date":"2019-06-09T23:34:00.095517-07:00",
         "bandwidth_use_end_date":"2019-07-09T23:34:00.095517-07:00",
         "verification_status": "not_required"
      }
   ]
}

HTTP Request

GET https://proxy.webshare.io/api/subuser/

URL Parameters

Parameter Default Description
page 1 Change the current page

Update a user

Update an existing user. You can partially update only the fields you wish to update.

import requests

response = requests.patch(
    "https://proxy.webshare.io/api/subuser/<ID>/",
    json={"label":"newlabel"}, 
    headers={"Authorization": "Token APIKEY"}
)
response.json()

curl "https://proxy.webshare.io/api/subuser/<ID>/" \
  -X PATCH \
  -d "{\"label\": \"newlabel\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "id":7,
   "label":"newlabel",
   "proxy_username":"eezocwls",
   "proxy_password":"r732w3h035mx",
   "proxy_countries": null,
   "proxy_limit":10.0,
   "proxy_usage":0,
   "last_use":null,
   "created_at":"2019-06-09T23:34:00.095501-07:00",
   "updated_at":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_start_date":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_end_date":"2019-07-09T23:34:00.095517-07:00",
   "verification_status": "not_required"
}

HTTP Request

GET https://proxy.webshare.io/api/subuser/<ID>/

URL Parameters

Parameter Description
ID The ID of the user to retrieve

Refresh proxy list of a user

Refresh the proxy list of a user. You can only perform this action if the user has a custom proxy list.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/subuser/<ID>/refresh/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()

curl "https://proxy.webshare.io/api/subuser/<ID>/refresh/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "id":7,
   "label":"newlabel",
   "proxy_username":"eezocwls",
   "proxy_password":"r732w3h035mx",
   "proxy_countries": null,
   "proxy_limit":10.0,
   "proxy_usage":0,
   "last_use":null,
   "created_at":"2019-06-09T23:34:00.095501-07:00",
   "updated_at":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_start_date":"2019-06-09T23:34:00.095517-07:00",
   "bandwidth_use_end_date":"2019-07-09T23:34:00.095517-07:00",
   "verification_status": "not_required"
}

HTTP Request

GET https://proxy.webshare.io/api/subuser/<ID>/refresh/

URL Parameters

Parameter Description
ID The ID of the Sub-user

Delete a user

This endpoint deletes a user.

import requests

response = requests.delete("https://proxy.webshare.io/api/subuser/<ID>/", headers={"Authorization": "Token APIKEY"})


curl "https://proxy.webshare.io/api/subuser/<ID>/" \
  -X DELETE \
  -H "Authorization: Token APIKEY"

The above command returns empty response with 204 HTTP status code

HTTP Request

DELETE https://proxy.webshare.io/api/subuser/<ID>/

URL Parameters

Parameter Description
ID The ID of the user to delete.

Masquerade as a user

You can make requests to Proxy Configuration, Proxy List and Proxy Stats APIs as a sub-user using the X-Webshare-SubUser header. More examples below.

import requests

response = requests.get("https://proxy.webshare.io/api/proxy/stats/", headers={
    "Authorization": "Token APIKEY",
    "X-Webshare-SubUser": "<User ID>"
})
response.json()

curl "https://proxy.webshare.io/api/proxy/stats/" \
  -H "Authorization: Token APIKEY" \
  -H "X-Webshare-SubUser: <User ID>"

The above command returns JSON structured like this:

{  
  "bandwidth_used": 5368709120,
  "bandwidth_remaining": 48318382080,
  "bandwidth_limit": 53687091200,
  "bandwidth_projected": 59055800320,

  "requests_total": 5000,
  "requests_countries":{"US":4000, "FR":500, "GB":500},
  "requests_successful": 4999,
  "requests_failed": 1,
  "request_failure_status_code":{"502": 1}
}

HTTP Request

Add X-Webshare-SubUser to any of the following APIs Proxy Configuration, Proxy List and Proxy Stats

URL Parameters

Parameter Description
User ID The ID of the user you wish to masquerade as

Rate Limits

The Webshare API uses rate limits for various endpoints.

API Name Rate
General API 180 requests every minute.
Proxy List API 60 requests every minute.
Proxy List Download Links 20 requests every minute.

If you encounter a rate limit, you will receive a 429 HTTP response. If you receive this error, you should wait up to 60 seconds and retry.

Errors

The Webshare API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Check the response body to see why.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You are forbidden to access the API. Upgrade your plan to gain access.
404 Not Found -- The specified resource could not be found. Maybe its deleted?
405 Method Not Allowed -- You tried to access a Webshare API with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Rate limited -- You have reached to the maximum number of requests you are allowed to send. Try again later.
500 Internal Server Error -- We had a problem with our server. We have been notified and working on fixing the issue. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
python shell