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/", headers={"Authorization": "Token <APIKEY>"})

# With shell, you can just pass the correct header with each request
curl "https://proxy.webshare.io/api/" \
  -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"
}

Reseller User 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,

  "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",

  "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
}

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.
rotate_frequency How often in seconds to rotate the proxy list. 0 value means do not rotate the proxy list.
rotate_percentage Percentage of proxies in the proxy list to rotate. Won't do anything if rotate_frequency is set to 0.
last_rotate_at Last time proxy list was rotated. Won't do anything if rotate_frequency is set to 0.
next_rotate_at Next time proxy list will be rotated. Won't do anything if rotate_frequency is set to 0.
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.

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",

  "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
}

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"]
}

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

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"]
}

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"]
}

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"]
}

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-5",
  "password": "jasdi2148",
  "proxy_address": "193.8.94.149",
  "ports": {"http":20004, "socks5":10004}
}

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.
ports Dictionary of ports by proxy protocol. Used for IP Authorization requests only.

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-5",
          "password": "jasdi2148",
          "proxy_address": "193.8.94.149",
          "ports": {"http":20004, "socks5":10004}
        },
        ...
    ]
}

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 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},
  "request_failure_status_codes":{"502": 1}
}

Reseller User 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.
request_failure_status_codes Dictionary of proxy request failure by status code.

Get user profile

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/

Reseller User

Create a reseller user

Create a new reseller user by setting label and bandwidth limit.

import requests

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

curl "https://proxy.webshare.io/api/reseller/" \
  -X POST \
  -d "{\"label\": \"newlabel\", \"proxy_limit\": 10}" \
  -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_limit":10.0,
   "proxy_usage":0,
   "last_use":null,
   "default_country_codes":null,
   "ip_address_authentication":[  

   ],
   "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/reseller/

Get a reseller user

This endpoint retrieves a specific reseller user.

import requests

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

curl "https://proxy.webshare.io/api/reseller/<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_limit":10.0,
   "proxy_usage":0,
   "last_use":null,
   "default_country_codes":null,
   "ip_address_authentication":[  

   ],
   "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

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

URL Parameters

Parameter Description
ID The ID of the reseller user to retrieve

List reseller users

This endpoint retrieves all reseller users in the system. 

import requests

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

curl "https://proxy.webshare.io/api/reseller/" \
  -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_limit":10.0,
         "proxy_usage":0,
         "last_use":null,
         "default_country_codes":null,
         "ip_address_authentication":[  

         ],
         "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

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

URL Parameters

Parameter Default Description
page 1 Change the current page

Update a reseller user

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

import requests

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

curl "https://proxy.webshare.io/api/reseller/<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_limit":10.0,
   "proxy_usage":0,
   "last_use":null,
   "default_country_codes":null,
   "ip_address_authentication":[  

   ],
   "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

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

URL Parameters

Parameter Description
ID The ID of the reseller user to retrieve

Delete a reseller user

This endpoint deletes a reseller user.

import requests

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


curl "https://proxy.webshare.io/api/reseller/<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/reseller/<ID>/

URL Parameters

Parameter Description
ID The ID of the reseller user to delete.

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