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 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:
- Auto-refresh your proxy list periodically (e.g. refresh once a day).
- On-demand refresh your proxy list when you wish to.
- 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. |