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,
"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"],
"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-5",
"password": "jasdi2148",
"proxy_address": "193.8.94.149",
"ports": {"http":20004, "socks5":10004},
"valid": true,
"last_verification": "2019-06-09T23:34:00.095501-07:00",
"country_code": "US",
"country_code_confidence": 0.95
}
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. |
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},
"valid": true,
"last_verification": "2019-06-09T23:34:00.095501-07:00",
"country_code": "US",
"country_code_confidence": 0.95
},
...
]
}
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},
"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/
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. |