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 examples in Shell and Python! 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/v2/profile/", headers={"Authorization": "Token <TOKEN>"})
# With shell, you can just pass the correct header with each request
curl "https://proxy.webshare.io/api/v2/profile/" \
  -H "Authorization: Token <TOKEN>"

Make sure to replace <TOKEN> with your API key.

Webshare uses token to allow access to the API. You will receive token after a successful login request. Alternatively, you can register a new Webshare API key at our API keys page.

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

Authorization: Token <TOKEN>

Register/Login

Webshare API supports both social and username/password based login and registration. Webshare API also supports social login with Google Auth.

Local Account

This endpoint enables registering and login with email and password. The email address verification (e.g. click on a link to verify email) is not part of this API. The token retrieved from both the register and login endpoints can be used to authorize API requests.

Register

You can register for a new account using the API requests as follows.

Register to Local Account

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/register/",
    json={
      "email": "user@webshare.io",
      "password": "password",
      "recaptcha": "...",
      "tos_accepted": True,
      "marketing_email_accepted": True,
    }
)
response.json()
curl https://proxy.webshare.io/api/v2/register/" \
  -X POST \
  -d "{\"email\": \"user@webshare.io\", \"password\": \"password\", \"recaptcha\": \"...\", \"tos_accepted\": true, \"marketing_email_accepted\": true}" \
  -H "Content-Type: application/json"

the above command returns JSON structured like this:

{
  "token": "AABB...ZZ"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/register/

Parameter Description
email Email address to register with. May require email validation (e.g. click the link) later on.
password Password requirements are: 8 characters minimum, not too similar to the email, must not be all numeric, must not be a common password.
recaptcha The recaptcha token (can be invisible recaptcha).
tos_accepted Must be true to process the request.
marketing_email_accepted Whether the service should send marketing emails to the customers.

Login

You can login to an existing account using the API requests as follows.

Login to Local Account

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/login/",
    json={
      "email": "user@webshare.io",
      "password": "password",
      "recaptcha": "..."
    }
)
response.json()
curl https://proxy.webshare.io/api/v2/login/" \
  -X POST \
  -d "{\"email\": \"user@webshare.io\", \"password\": \"password\", \"recaptcha\": \"...\"}" \
  -H "Content-Type: application/json"

the above command returns JSON structured like this:

{
  "token": "AABB...ZZ"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/login/

Parameter Description
email Email address previously registered with.
password Password previously registered with.
recaptcha The recaptcha token (can be invisible recaptcha).

Social Account

This endpoint enables registering and login with social account (e.g. Google OAuth2). The token retrieved from both the register and login endpoints can be used to authorize API requests.

Register

You can register for a new account using the API requests as follows.

Register to Social Account

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/register/social/",
    json={
      "provider": "google",
      "code": "4/...",
      "redirect_uri": "https://proxy2.webshare.io",
      "tos_accepted": True,
      "marketing_email_accepted": True,
    }
)
response.json()
curl https://proxy.webshare.io/api/v2/register/social/" \
  -X POST \
  -d "{\"provider\": \"google\", \"code\": \"4/...\", \"redirect_uri\": \"https://proxy2.webshare.io\", \"tos_accepted\": true, \"marketing_email_accepted\": true}" \
  -H "Content-Type: application/json"

the above command returns JSON structured like this:

{
  "token": "AABB...ZZ"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/register/social/

Parameter Description
provider Social provider to login with. Currently only google is supported.
code Then auth code received from the social provider.
redirect_uri Must match the authorized redirect URIs Google Credentials.
tos_accepted Must be true to process the request.
marketing_email_accepted Whether the service should send marketing emails to the customers.

Login

You can login to an existing social account using the API requests as follows.

Login to Social Account

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/login/social/",
    json={
      "provider": "google",
      "code": "4/...",
      "redirect_uri": "https://proxy2.webshare.io",
    }
)
response.json()
curl https://proxy.webshare.io/api/v2/login/social/" \
  -X POST \
  -d "{\"provider\": \"google\", \"code\": \"4/...\", \"redirect_uri\": \"https://proxy2.webshare.io\"}" \
  -H "Content-Type: application/json"

the above command returns JSON structured like this:

{
  "token": "AABB...ZZ"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/login/social/

Parameter Description
provider Social provider to login with. Currently only google is supported.
code Then auth code received from the social provider.
redirect_uri Must match the authorized redirect URIs Google Credentials.

Change Password

This endpoint enables changing your existing password.

Reset Password Request

Change your current password to a new password. Upon a successful password change, all API tokens will be disabled except the current one.

If a user has registered with Google Oauth, they may not have a password. In that case, they must use reset password endpoint instead.

**Password Reset request

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/changepassword/",
    json={
        "password": "currentpassword",
        "new_password": "new_password1088"
    }, 
    headers={"Authorization": "Token APITOKEN"}
)
response.json()
curl https://proxy.webshare.io/api/v2/changepassword/" \
  -X POST \
  -d "{\"password\": \"currentpassword\", \"new_password\":\"new_password1088\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APITOKEN"

*the above command returns empty response with 204 No Content status code

HTTP Request

POST https://proxy.webshare.io/api/v2/changepassword/

Parameter Description
password Current password.
new_password New password. Must meet all password requirements (similar to registration)

Reset Password

This endpoint enables sending API calls for a new password reset request and complete an existing password reset with a password_reset_token retrieved from the email.

Reset Password Request

Request a new password reset for a user. If successful, the API send an email to the user. Beyond basic email/recaptcha validation, this API always returns 204 response even if the email is not found. Email validation only checks if the given email is in the correct format.

**Password Reset request

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/resetpassword/",
    json={
        "email": "user@webshare.io",
        "recaptcha": "..."
    }
)
response.json()
curl https://proxy.webshare.io/api/v2/resetpassword/" \
  -X POST \
  -d "{\"email\": \"user@webshare.io\", \"recaptcha\": \"...\"}" \
  -H "Content-Type: application/json"

*the above command returns empty response with 204 No Content status code

HTTP Request

POST https://proxy.webshare.io/api/v2/resetpassword/

Parameter Description
email Email of the existing user. Email validation only checks if the given email is in the correct format.
recaptcha The recaptcha token (can be invisible recaptcha).

Complete Password Request

Complete the password reset using the password_reset_token retrieved from the email. If password reset is successful, all previous API tokens will be invalidated and you will receive a new token.

The reset password email contains a link which redirects to the following URL:

https://proxy2.webshare.io/resetpassword/{password_reset_token}/confirm/

**Complete Password Reset request

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/resetpassword/complete/",
    json={
        "password": "newpassword1088",
        "password_reset_token": "aabb...99",
        "recaptcha": "..."
    }
)
response.json()
curl https://proxy.webshare.io/api/v2/resetpassword/complete/" \
  -X POST \
  -d "{\"password\": \"newpassword1088\", \"password_reset_token\": \"aabb...99\", \"recaptcha\": \"...\"}" \
  -H "Content-Type: application/json"

the above command returns JSON structured like this:

{
  "token": "AABB...ZZ"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/resetpassword/complete/

Parameter Description
password New password for the user.
password_reset_token Verification code retrieved from the email.
recaptcha The recaptcha token (can be invisible recaptcha).

Change Email

This endpoint enables sending API calls for an email change request and complete an existing change request with a change_email_token retrieved from the email.

Change Email Request

Request a new email change for a user. If successful, the API sends an email to the user. Beyond basic email validation, this API always returns 204 response. Email validation checks if the email exists in the system.

**Change Email request

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/changeemail/",
    json={
        "new_email": "newemail@webshare.io"
    },
    headers={"Authorization": "Token APITOKEN"}
)
response.json()
curl https://proxy.webshare.io/api/v2/changeemail/" \
  -X POST \
  -d "{\"new_email\": \"newemail@webshare.io\"}" \
  -H "Authorization: Token APITOKEN" \
  -H "Content-Type: application/json"

*the above command returns empty response with 204 No Content status code

HTTP Request

POST https://proxy.webshare.io/api/v2/changeemail/

Parameter Description
new_email New email address we are switching to to. Email validation checks if the email already exists in the system.

Complete Change Email Request

Complete the change email request using the change_email_token retrieved from the email. The change email contains a link which redirects to the following URL:

https://proxy2.webshare.io/changeemail/{change_email_token}/confirm/

The user must be logged into their account to complete the change email request.

**Complete Change Email request

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/changeemail/complete/",
    json={
        "password": "newpassword1088",
        "change_email_token": "aabb...99"
    },
    headers={"Authorization": "Token APITOKEN"}
)
response.json()
curl https://proxy.webshare.io/api/v2/changeemail/complete/" \
  -X POST \
  -d "{\"password\": \"newpassword1088\", \"change_email_token\": \"aabb...99\"}" \
  -H "Authorization: Token APITOKEN" \
  -H "Content-Type: application/json"

*the above command returns empty response with 204 No Content status code

HTTP Request

POST https://proxy.webshare.io/api/v2/changeemail/complete/

Parameter Description
password Password of the user.
change_email_token Token retrieved from the email.

Activate Account

Accounts in some cases may require email activation before being able to do certain actions. You can activate or resend activation emails using the APIs below.

Get Activation Status

This endpoint retrieves the current state of the account activation.

Get Activation Status request

import requests

response = requests.get("https://proxy.webshare.io/api/v2/activation/", headers={"Authorization": "Token APITOKEN"})
response.json()
curl "https://proxy.webshare.io/api/v2/activation/" \
  -H "Authorization: Token APITOKEN"

The above command returns JSON structured like this:

{
  "email_is_verified": false,
  "last_time_email_verification_email_sent": null,
  "created_at": "2019-05-09T23:34:00.095501-07:00",
  "updated_at": "2019-05-09T23:34:00.095501-07:00"
}

Activation Status Object

Attributes Description
email_is_verified Whether the email is verified or not.
last_time_email_verification_email_sent Last time the account activation email was sent. May be null. ISO 8601 format with timestamp.
created_at The time the activation status object was created. ISO 8601 format with timestamp.
updated_at The last time the activation status was updated. ISO 8601 format with timestamp.

Resend Activation Email

This endpoint re-sends activation email to the user's registered email address. There is a limit on how often a user can re-send activation emails. The API returns the Activation Status object on success.

Resend Activation Email request

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/activation/resend/", 
    json={},
    headers={"Authorization": "Token APITOKEN"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/activation/resend/" -X POST \
  -H "Authorization: Token APITOKEN"

the above command returns JSON structured like this:

{
  "email_is_verified": false,
  "last_time_email_verification_email_sent": "2019-05-09T23:34:00.095501-07:00",
  "created_at": "2019-05-09T23:34:00.095501-07:00",
  "updated_at": "2019-05-09T23:34:00.095501-07:00"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/activation/resend/

The request does not contain a body.

Complete Account Activation

Use the activation token you have received from the email to complete the account activation. A successful activation will return you a new API token. You can still continue using your existing API token. This API doesn't require authentication headers, although you are encouraged to send the headers.

The email contains a link which redirects to the following URL:

https://proxy2.webshare.io/activation/{activation_token}/confirm/

Complete Account Activation request

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/activation/complete/",
    json={
        "activation_token": "aabb...99"
    }
)
response.json()
curl https://proxy.webshare.io/api/v2/activation/complete/" \
  -X POST \
  -d "{\"activation_token\": \"aabb...99\"}" \
  -H "Content-Type: application/json"

the above command returns JSON structured like this:

{
  "token": "AABB...ZZ"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/activation/complete/

Parameter Description
activation_token Activation token retrieved from the email.

Logout

You can logout to invalidate the token you are using.

import requests

response = requests.get("https://proxy.webshare.io/api/v2/logout/", headers={"Authorization": "Token APITOKEN"})
response.json()
curl "https://proxy.webshare.io/api/v2/logout/" \
  -X POST \
  -H "Authorization: Token APITOKEN"

The above command returns 204 No Content status with no response body:

HTTP Request

POST https://proxy.webshare.io/api/v2/logout/

User Profile

The user profile object

You can use the API to retrieve information about your user preferences

The user profile object

{ 
  "id": 1,
  "email": "user@webshare.io",
  "first_name": "",
  "last_name": "",
  "last_login": "2022-06-14T15:59:06.663774-07:00",
  "timezone": "America/Los_Angeles",
  "subscribed_bandwidth_usage_notifications": true,
  "subscribed_subscription_notifications": true,
  "subscribed_proxy_usage_statistics": true,
  "subscribed_usage_warnings": true,
  "subscribed_guides_and_tips": true,
  "subscribed_survey_emails": true,
  "tracking_id": "f5f40cb1-8752-4685-b0d0-91dd09684750",
  "helpscout_beacon_signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "announce_kit_user_token": "ey...Xs",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

User Profile Object

Attributes Description
id Unique identifier of the profile instance
email Email address of the user. Read-only.
first_name First name of the user. Can be set to empty.
last_name First name of the user. Can be set to empty.
created_at The date user was registered. Read-only.
last_login The date user last logged in. Read-only.
timezone The preferred timezone set by the user.
subscribed_bandwidth_usage_notifications Subscribed to email notifications for bandwidth usage.
subscribed_subscription_notifications Subscribed to email notifications for subscription updates.
subscribed_proxy_usage_statistics Subscribed to email notifications for proxy usage statistics/insights.
subscribed_usage_warnings Subscribed to email notifications for proxy usage warnings.
subscribed_guides_and_tips Subscribed to email notifications for guides and tips for your proxy usage.
subscribed_survey_emails Subscribed to email notifications for surveys.
tracking_id Unique ID for this user. May be used while identifying the user with external services.
helpscout_beacon_signature Helpscout signature used to identify the user
announce_kit_user_token Announcekit User Token JWT token for the user_token field.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this instance was last updated.

Get user profile

This endpoint retrieves the user profile.

import requests

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

The above command returns JSON structured like this:

{
  "id": 1,
  "email": "user@webshare.io",
  "first_name": "",
  "last_name": "",
  "last_login": "2022-06-14T15:59:06.663774-07:00",
  "timezone": "America/Los_Angeles",
  "subscribed_bandwidth_usage_notifications": true,
  "subscribed_subscription_notifications": true,
  "subscribed_proxy_usage_statistics": true,
  "subscribed_usage_warnings": true,
  "subscribed_guides_and_tips": true,
  "subscribed_survey_emails": true,
  "tracking_id": "f5f40cb1-8752-4685-b0d0-91dd09684750",
  "helpscout_beacon_signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "announce_kit_user_token": "ey...Xs",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

Update user profile

This endpoint updates the user profile.

import requests

response = requests.patch(
    "https://proxy.webshare.io/api/v2/profile/",
    json={
        "timezone":"America/New_York"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/profile/" \
  -X PATCH \
  -d "{\"timezone\": [\"America/New_York\"]}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "email": "user@webshare.io",
  "first_name": "",
  "last_name": "",
  "last_login": "2022-06-14T15:59:06.663774-07:00",
  "timezone": "America/Los_Angeles",
  "subscribed_bandwidth_usage_notifications": true,
  "subscribed_subscription_notifications": true,
  "subscribed_proxy_usage_statistics": true,
  "subscribed_usage_warnings": true,
  "subscribed_guides_and_tips": true,
  "subscribed_survey_emails": true,
  "tracking_id": "f5f40cb1-8752-4685-b0d0-91dd09684750",
  "helpscout_beacon_signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "announce_kit_user_token": "ey...Xs",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

PATCH https://proxy.webshare.io/api/v2/profile/

Proxy List

You can use the Webshare API to retrieve your proxy list in 2 modes: direct and backbone. Each mode returns the same proxy data structure with minor changes on how the fields are used.

Backbone Proxy

Backbone proxy connections always use p.webshare.io connection address. In username/password authentication, the following ports can be used: 80, 1080, 3128 and 9999 - 19999. The IP Authentication mode, you must use the port field returned from the API.

Direct Proxy

Direct proxy connections use the proxy_address and port field returned from the API. Same fields are used across username/password and IP Authentication modes.

The proxy object

The proxy object

{  
  "id": "d-10513",
  "username": "username",
  "password": "password",
  "proxy_address": "1.2.3.4",
  "port": 8168,
  "valid": true,
  "last_verification": "2019-06-09T23:34:00.095501-07:00",
  "country_code": "US",
  "city_name": "New York",
  "created_at": "2022-06-14T11:58:10.246406-07:00"
}
Attributes Description
id Unique identified of the proxy instance. Type is string.
username Proxy username.
password Proxy password.
proxy_address IP Address of the proxy. In Direct Connection mode, connect to this IP address. In Backbone Connection mode, connect to p.webshare.io.
port Port used to connect to the proxies. In Backbone mode, the port is always set for IP Authorization.
valid If the proxy is working as expected. Webshare checks proxies once every 30 seconds.
last_verification Last time the proxy was checked.
country_code The country code of the proxy.
city_name The city name of the proxy.
created_at The timestamp of when this instance was created.

List proxies

This endpoint returns the proxy list in paginated format. The mode parameter must always be specified.

Retrieve Proxy List

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/proxy/list/?mode=direct&page=1&page_size=25", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/list/?mode=direct&page=1&page_size=25" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "count": 10,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "d-10513",
      "username": "username",
      "password": "password",
      "proxy_address": "1.2.3.4",
      "port": 8168,
      "valid": true,
      "last_verification": "2019-06-09T23:34:00.095501-07:00",
      "country_code": "US",
      "city_name": "New York",
      "created_at": "2022-06-14T11:58:10.246406-07:00"
    },
    ...
  ]
}

HTTP Request

Parameter Description
mode Must be either direct or backbone. Required field.
country_code__in Filter by comma separated country code. Example filtering USA and French proxies: FR,US. Optional field.
search Filter by a search phrase. Can accept arbitrary text. Optional field.
ordering Comma separated list of fields to specify ordering. Reverse ordering (DESC) can be achieved by adding minus in front of the field. Example: -valid,proxy_address. Optional field. Ordering is not supported in the backbone mode.

Download proxy list

You can download the proxy list as a file using the links below. These links use proxy_list_download_token which can be retrieved from the Proxy Config API.

This API does not require authentication.

The proxy download URL

https://proxy.webshare.io/api/v2/proxy/list/download/{token}/{country_codes}/any/{authentication_method}/{endpoint_mode}/{search}/

Proxy download URL parameters

Key Description
token Token retrieved from the Proxy Config API.
country_codes country code separated by hyphen (-). In order to select all countries, use -
authentication_method username or sourceip. Determines the authentication method to access to the proxies.
endpoint_mode backbone or direct. Determines the proxy format.
search URL encoded search terms. Can be set as - to indicate no search terms.
import requests
response = requests.get("https://proxy.webshare.io/api/v2/proxy/list/download/aabb..zz/-/any/username/direct/san%20francisco/")
response.text
curl "https://proxy.webshare.io/api/v2/proxy/list/download/aabb..zz/-/any/username/direct/san%20francisco/"

The above command returns response structured like this:

10.1.2.3:9421:username:password
10.1.2.4:6511:username:password

Refresh proxy list

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

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/proxy/list/refresh/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/list/refresh/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns 204 No Content status with no response body

HTTP Request

POST https://proxy.webshare.io/api/v2/proxy/list/refresh/

Proxy Replacement

You can replace and list the replaced proxies using the Proxy Replacement API. There are 2 main endpoints for replacing proxies.

  1. Proxy Replacement: Set of rules indicating which proxies to replace from and replace with in a proxy list.
  2. Replaced Proxy: List of replaced proxies which can be filtered by proxy replacement or the proxy list.

The proxy replacement object

The proxy replacement object

{
    "id": 98315,
    "to_replace": {"type": "ip_range", "ip_range": "1.2.3.4/32"},
    "replace_with": [{"type": "country", "country_code": "US"}],
    "dry_run": false,
    "state": "completed",
    "proxies_removed": 1,
    "proxies_added": 1,
    "created_at": "2022-07-26T21:25:13.966946-07:00",
    "completed_at": "2022-07-26T21:25:13.966946-07:00",
}
Attributes Description
id Unique identified of the proxy replacement instance.
to_replace Dictionary indicating which proxies to replace. Complete field definition can be found below.
replace_with List of dictionaries indicating which proxies to replace with. Complete field definition can be found below.
proxies_removed Number of proxies removed from the proxy list.
proxies_added Number of proxies added to the proxy list.
state The current state of the proxy replacement can be: pending, processing, completed and failed. If failed, show a generic error message (e.g. Webshare team is notified)
dry_run You can dry-run a replacement to learn number of proxies removed/added prior to actually replacing the proxy list. dry_run=True does not modify the proxy list.
created_at The timestamp of when this instance was created.
completed_at The timestamp of when this instance state became completed. May be null.

to_replace/replace_with definitions

There are 3 types for to_replace/replace_with fields. replace_with may be a list of dictionaries/types as we may not have enough replacements from one country.

For example, if we want to replace 10 US proxies with 5 French and 5 Turkish, you can use the fields as follows:

type=ip_range
Attributes Description
type Set to ip_range. Indicates which proxy IP addresses to replace or replace with.
ip_range IP range in CIDR notation. E.g. 10.0.0.0/8. Host bits may not be set. For example, 10.0.0.1/8 is invalid. However, 10.0.0.1/32 is valid.
count Number of proxies to replace with.
type=country
Attributes Description
type Set to country. Indicates which proxy countries to replace or replace with.
country_code Country code in ISO-3166 format.
count Number of proxies to replace with.
type=any
Attributes Description
type Set to any. Only used in the replace_with field.
count Number of proxies to replace with.

Create proxy replacement

This endpoint lets you create a proxy replacements which replaces proxies from your proxy list. The proxies_removed and proxies_added must always match.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/proxy/replace/", 
    json={
        "to_replace": {"type": "ip_range", "ip_range": "1.2.3.4/32"},
        "replace_with": [{"type": "country", "country_code": "US"}],
        "dry_run": False
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/replace/" \
  -X POST \
  -d "{\"to_replace\": {\"type\": \"ip_range\", \"ip_range\": \"1.2.3.4/32\"}, \"replace_with\": [{\"type\": \"country\", \"country_code\": \"US\"}], \"dry_run\": false}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
    "id": 98315,
    "to_replace": {"type": "ip_range", "ip_range": "1.2.3.4/32"},
    "replace_with": [{"type": "country", "country_code": "US"}],
    "dry_run": false,
    "state": "completed",
    "proxies_removed": 1,
    "proxies_added": 1,
    "created_at": "2022-07-26T21:25:13.966946-07:00",
    "completed_at": "2022-07-26T21:25:13.966946-07:00",
}

HTTP Request

POST https://proxy.webshare.io/api/v2/proxy/replace/

Create proxy replacement request

Attributes Description
to_replace Dictionary indicating which proxies to replace.
replace_with List of dictionaries indicating which proxies to replace with.
dry_run You can dry-run a replacement to learn number of proxies removed/added prior to actually replacing the proxy list. dry_run=True does not modify the proxy list.

400 Errors

Error Code Description
proxies_removed_doesnt_match_added There is a mismach between added and replaced proxies.
not_enough_replacements_in_subscription Account holder doesn't have enough proxy replacements.

List proxy replacement

This endpoint retrieves all existing proxy replacements associated with the user in paginated format with filtering & ordering enabled.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/proxy/replace/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/replace/" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
        "id": 98315,
        "to_replace": {"type": "ip_range", "ip_range": "1.2.3.4/32"},
        "replace_with": [{"type": "country", "country_code": "US"}],
        "dry_run": false,
        "state": "completed",
        "proxies_removed": 1,
        "proxies_added": 1,
        "created_at": "2022-07-26T21:25:13.966946-07:00",
        "completed_at": "2022-07-26T21:25:13.966946-07:00",
    },
    ...
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/proxy/replace/

URL Parameters

Parameter Description
ordering Default ordering is id. Available ordering fields are id, created_at, completed_at.
dry_run Filter proxy replacements with whether it is dry run or not.
state Filter proxy replacements by state

Get proxy replacement

This endpoint lets you get an existing proxy replacements.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/proxy/replace/<ID>/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/replace/<ID>/" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
    "id": 98315,
    "to_replace": {"type": "ip_range", "ip_range": "1.2.3.4/32"},
    "replace_with": [{"type": "country", "country_code": "US"}],
    "dry_run": false,
    "state": "completed",
    "proxies_removed": 1,
    "proxies_added": 1,
    "created_at": "2022-07-26T21:25:13.966946-07:00",
    "completed_at": "2022-07-26T21:25:13.966946-07:00",
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the proxy replacement to retrieve.

The replaced proxy object

The replaced proxy object

{
    "id": 93892,
    "proxy": "45.158.184.116",
    "proxy_port": 9192,
    "replaced_with": "104.227.101.59",
    "replaced_with_port": 6120,
    "created_at": "2022-07-26T21:25:13.966946-07:00"
}
Attributes Description
id Unique identified of the replaced proxy instance.
proxy The IP address of the replaced proxy.
proxy_port The port of the replaced proxy.
replaced_with The IP address of the new proxy.
replaced_with_port The port of the new proxy.
created_at The timestamp of when this instance was created.

List replaced proxies

This endpoint returns the replaced proxy list in paginated format.

List replaced proxies

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/proxy/list/replaced/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/list/replaced/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "count": 10,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 93892,
      "proxy": "45.158.184.116",
      "proxy_port": 9192,
      "replaced_with": "104.227.101.59",
      "replaced_with_port": 6120,
      "created_at": "2022-07-26T21:25:13.966946-07:00"
    },
    ...
  ]
}

HTTP Request

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

Parameter Description
created_at__gte Filter proxies replaced after the given datetime in ISO 8601 format.
created_at__lte Filter proxies replaced before the given datetime in ISO 8601 format.
proxy Filter by the replaced proxy address.
replaced_with Filter by the new proxy address.
proxy_list_replacement Filter by the proxy replacement id.
search Filter by a search phrase. Can accept arbitrary text.
ordering Comma separated list of fields to specify ordering. Reverse ordering (DESC) can be achieved by adding minus in front of the field. Example: proxy,-created_at.

Proxy Configuration

The proxy config object

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

The proxy config object

{
  "id": 1,
  "state": "completed",
  "countries": {"US":5, "FR":100},
  "available_countries": {"US": 95},
  "unallocated_countries": {},
  "ip_ranges_24": {"10.1.1.0/24": 5, "10.1.3.0/24": 100},
  "ip_ranges_16": {"10.1.0.0/16": 105},
  "ip_ranges_8": {"10.0.0.0/24": 105},
  "available_ip_ranges_24": {"1.2.3.0/24": 100},
  "available_ip_ranges_16": {"1.2.3.0/24": 100},
  "available_ip_ranges_8": {"1.2.3.0/24": 100},
  "username": "username",
  "password": "password",
  "request_timeout": 86400,
  "request_idle_timeout": 900,
  "ip_authorization_country_codes": ["US", "FR"],
  "auto_replace_invalid_proxies": true,
  "auto_replace_low_country_confidence_proxies": false,
  "auto_replace_out_of_rotation_proxies": false,
  "proxy_list_download_token": "aa87abbc...zz",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

Proxy Config Object

Attributes Description
id Unique identifier of the proxy configuration instance.
state Indicates whether a proxy list is ready to use or not. Values can be pending, processing or completed.
countries Proxy countries by count in the proxy list. Cannot be edited.
available_countries Proxy countries by count available (not in the current proxy list). This field is useful when listing which countries are available when replacing proxies. Cannot be edited.
unallocated_countries Unallocated proxy countries by count. A proxy becomes unallocated if the Plan object requested for a specific country but that country was not available to be allocated for the Proxy List.
ip_ranges_24 IP ranges in /24 subnet by count in the proxy list. Format is CIDR:count. Cannot be edited.
ip_ranges_16 IP ranges in /16 subnet by count in the proxy list. Format is CIDR:count. Cannot be edited.
ip_ranges_8 IP ranges in /8 subnet by count in the proxy list. Format is CIDR:count. Cannot be edited.
available_ip_ranges_24 IP ranges in /24 subnet by count available (not in the current proxy list). This field is useful when listing which IP ranges are available when replacing proxies. Format is CIDR:count. Cannot be edited.
available_ip_ranges_16 IP ranges in /16 subnet by count available (not in the current proxy list). This field is useful when listing which IP ranges are available when replacing proxies. Format is CIDR:count. Cannot be edited.
available_ip_ranges_8 IP ranges in /8 subnet by count available (not in the current proxy list). This field is useful when listing which IP ranges are available when replacing proxies. Format is CIDR:count. Cannot be edited.
username Proxy username. Must be between 8-32 characters, alphanumeric.
password Proxy password. Must be between 8-32 characters, alphanumeric. Cannot be too common password. Cannot be too similar to proxy username.
request_timeout Maximum number of seconds a proxy request can be used. Min value is 15 seconds. Max value is 7 days.
request_idle_timeout Maximum number of seconds a proxy request can stay idle (no data sent). Min value is 15 seconds. Max value is 2 hours.
ip_authorization_country_codes The list of country codes the proxy should server for IP Authorization in Backbone Connection mode. If set to null, all countries are available.
auto_replace_invalid_proxies Auto-replace proxies from the proxy list if they are invalid for 15 minutes. Cannot be edited for free proxy plans.
auto_replace_low_country_confidence_proxies Auto-replace proxies from the proxy list if they have low country confidence. Cannot be edited for free proxy plans.
auto_replace_out_of_rotation_proxies Auto-replace proxies from the proxy list if they are performing slower than usual.
proxy_list_download_token Alpha-numeric randomly generated token used for proxy list download links.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this instance was last updated.

Get proxy config

This endpoint retrieves the proxy config.

import requests

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

The above command returns JSON structured like this:

{
  "id": 1,
  "state": "completed",
  "countries": {"US":5, "FR":100},
  "available_countries": {"US": 95},
  "unallocated_countries": {},
  "ip_ranges_24": {"10.1.1.0/24": 5, "10.1.3.0/24": 100},
  "ip_ranges_16": {"10.1.0.0/16": 105},
  "ip_ranges_8": {"10.0.0.0/24": 105},
  "available_ip_ranges_24": {"1.2.3.0/24": 100},
  "available_ip_ranges_16": {"1.2.3.0/24": 100},
  "available_ip_ranges_8": {"1.2.3.0/24": 100},
  "username": "username",
  "password": "password",
  "request_timeout": 86400,
  "request_idle_timeout": 900,
  "ip_authorization_country_codes": ["US", "FR"],
  "auto_replace_invalid_proxies": true,
  "auto_replace_low_country_confidence_proxies": false,
  "auto_replace_out_of_rotation_proxies": false,
  "proxy_list_download_token": "aa87abbc...zz",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

Update proxy config

This endpoint updates the proxy config.

import requests

response = requests.patch(
    "https://proxy.webshare.io/api/v2/proxy/config/",
    json={
        "username":"new_username"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/config/" \
  -X PATCH \
  -d "{\"username\": \"new_username\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "state": "completed",
  "countries": {"US":5, "FR":100},
  "available_countries": {"US": 95},
  "unallocated_countries": {},
  "ip_ranges_24": {"10.1.1.0/24": 5, "10.1.3.0/24": 100},
  "ip_ranges_16": {"10.1.0.0/16": 105},
  "ip_ranges_8": {"10.0.0.0/24": 105},
  "available_ip_ranges_24": {"1.2.3.0/24": 100},
  "available_ip_ranges_16": {"1.2.3.0/24": 100},
  "available_ip_ranges_8": {"1.2.3.0/24": 100},
  "username": "username",
  "password": "password",
  "request_timeout": 86400,
  "request_idle_timeout": 900,
  "ip_authorization_country_codes": ["US", "FR"],
  "auto_replace_invalid_proxies": true,
  "auto_replace_low_country_confidence_proxies": false,
  "auto_replace_out_of_rotation_proxies": false,
  "proxy_list_download_token": "aa87abbc...zz",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

PATCH https://proxy.webshare.io/api/v2/proxy/config/

Reset download token

This endpoint resets the proxy_list_download_token.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/proxy/config/reset_download_token/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/config/reset_download_token/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "state": "completed",
  "countries": {"US":5, "FR":100},
  "available_countries": {"US": 95},
  "unallocated_countries": {},
  "ip_ranges_24": {"10.1.1.0/24": 5, "10.1.3.0/24": 100},
  "ip_ranges_16": {"10.1.0.0/16": 105},
  "ip_ranges_8": {"10.0.0.0/24": 105},
  "available_ip_ranges_24": {"1.2.3.0/24": 100},
  "available_ip_ranges_16": {"1.2.3.0/24": 100},
  "available_ip_ranges_8": {"1.2.3.0/24": 100},
  "username": "username",
  "password": "password",
  "request_timeout": 86400,
  "request_idle_timeout": 900,
  "ip_authorization_country_codes": ["US", "FR"],
  "auto_replace_invalid_proxies": true,
  "auto_replace_low_country_confidence_proxies": false,
  "auto_replace_out_of_rotation_proxies": false,
  "proxy_list_download_token": "aa87abbc...zz",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

Allocate unallocated countries

This endpoint allocates the proxies in unallocated_countries state. If there are 5 unallocated countries, you must send new_countries with 5 countries in total. All new_countries must be valid and available

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/proxy/config/allocate_unallocated_countries/",
    json={
        "new_countries":{
            "FR":5
        }
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/config/allocate_unallocated_countries/" \
  -X POST \
  -d "{\"new_countries\": {\"FR\":5}}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "state": "completed",
  "countries": {"US":5, "FR":100},
  "available_countries": {"US": 95},
  "unallocated_countries": {},
  "ip_ranges_24": {"10.1.1.0/24": 5, "10.1.3.0/24": 100},
  "ip_ranges_16": {"10.1.0.0/16": 105},
  "ip_ranges_8": {"10.0.0.0/24": 105},
  "available_ip_ranges_24": {"1.2.3.0/24": 100},
  "available_ip_ranges_16": {"1.2.3.0/24": 100},
  "available_ip_ranges_8": {"1.2.3.0/24": 100},
  "username": "username",
  "password": "password",
  "request_timeout": 86400,
  "request_idle_timeout": 900,
  "ip_authorization_country_codes": ["US", "FR"],
  "auto_replace_invalid_proxies": true,
  "auto_replace_low_country_confidence_proxies": false,
  "auto_replace_out_of_rotation_proxies": false,
  "proxy_list_download_token": "aa87abbc...zz",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

Attributes Description
new_countries Number of proxies by country_code:count. Country code must be upper case and count must be greater than 0.

IP Authorization

Webshare proxy offers 2 methods for authenticating with the proxies: password and IP Authorization. If you do not wish to use password authentication, you can instead authorize your IP address using this API.

The IP authorization object

Each IP Authorization instance has the following fields

The IP authorization object

{
  "id": 1337,
  "ip_address": "10.1.2.3",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "last_used_at": null
}

IP Authorization Object

Attributes Description
id The unique ID of the IP Authorization object.
ip_address The IP address which is authorized to connect to the proxies without username/password.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this IP address was last used.

Create IP authorization

This endpoint lets you create an IP authorization.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/proxy/ipauthorization/", 
    json={"ip_address": "10.1.2.3"},
    headers={"Authorization": "Token APIKEY"})
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/ipauthorization/" \
  -X POST \
  -d "{\"ip_address\": \"10.1.2.3\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1337,
  "ip_address": "10.1.2.3",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "last_used_at": null
}

HTTP Request

POST https://proxy.webshare.io/api/v2/proxy/ipauthorization/

Create IP authorization request

Attributes Description
ip_address The IP address to authorize. May return 400 error if this IP address is already authorized in the system.

What's my ip

This endpoint lets you get your public IP address. It may be useful for IP Authorization purposes.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/proxy/ipauthorization/whatsmyip/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/ipauthorization/whatsmyip/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "ip_address": "1.2.3.4"
}

HTTP Request

GET https://proxy.webshare.io/api/v2/proxy/ipauthorization/whatsmyip/

List IP authorizations

This endpoint returns the proxy IP authorizations in paginated format.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/proxy/ipauthorization/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/ipauthorization/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1337,
      "ip_address": "10.1.2.3",
      "created_at": "2022-06-14T11:58:10.246406-07:00",
      "last_used_at": null
    },
    ...
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/proxy/ipauthorization/

Get IP authorization

This endpoint lets you retrieve an IP authorization.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/proxy/ipauthorization/<ID>/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/ipauthorization/<ID>/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1337,
  "ip_address": "10.1.2.3",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "last_used_at": null
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the IP authorization to retrieve.

Delete IP authorization

This endpoint lets you delete an IP authorization.

import requests

response = requests.delete(
    "https://proxy.webshare.io/api/v2/proxy/ipauthorization/<ID>/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/ipauthorization/<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/v2/proxy/ipauthorization/<ID>/

URL Parameters

Parameter Description
ID The ID of the IP authorization to delete.

Proxy Stats

You can use the Webshare API to retrieve the proxy statistics.

The proxy stats object

Proxy stats are by default aggregated every 1 hour.

The proxy stats object

{
  "timestamp": "2022-08-11T17:00:00-07:00",
  "is_projected": false,
  "bandwidth_total": 5000,
  "bandwidth_average": 1000,
  "requests_total": 5,
  "requests_successful": 4,
  "requests_failed": 1,
  "error_reasons": [
    {
      "reason": "client_connect_forbidden_host",
      "type": "configuration",
      "how_to_fix": "The target website you are connecting cannot be accessed via Webshare Proxy.",
      "http_status": 403,
      "count": 1
    }
  ],
  "countries_used": {
    "GB": 1,
    "FR": 4
  },
  "number_of_proxies_used": 2,
  "protocols_used": {
    "http": 5
  },
  "average_concurrency": 0.0001388888888888889,
  "average_rps": 0.0002777777777777778,
  "last_request_sent_at": "2022-08-11T17:12:32.589667-07:00"
}

The proxy stats object attributes

Attributes Description
timestamp The timestamp of the stat. The stats are always aggregated for 1 hour (3,600 seconds). All timestamps have 00:00 minute&second. ISO 8601 format.
is_projected Indicates whether the stat is projected or real. You may request projected stats for the future.
bandwidth_total Total bandwidth use in bytes for the 1 hour window.
bandwidth_average Average bandwidth in bytes per request. Calculated by bandwidth_total/requests_total.
requests_total Number of proxy requests made.
requests_failed Number of proxy requests failed.
error_reasons List of error reasons. Detailed attributes can be found in the table below. Set to [] if is_projected=True.
countries_used Number of proxy requests per country code. Set to {} if is_projected=True.
number_of_proxies_used Number of unique proxy addresses used (estimated). If backbone proxy is used, the number of unique assigned IP addresses are counted. Set to 0 if is_projected=True.
protocols_used Number of requests per proxy protocol. Protoxy protocols can be http or socks. Set to {} if is_projected=True.
average_concurrency Average number of concurrent proxy request (estimated). Set to null if is_projected=True.
average_rps Average proxy requests per second (estimated). Set to null if is_projected=True.
last_request_sent_at The time last proxy request was sent. Must be within the 1 hour window. Set to null if is_projected=True.

The error reason object attributes

Attributes Description
reason Code for the error. The same code is present in the X-Webshare-Error-Reason header when making requests to the HTTP proxy endpoint.
type Whether the error is a configuration or connection error.
how_to_fix Guide for the end-user on how to fix the error.
http_status HTTP response status code the HTTP proxy endpoint may return for this particular error. May be null.
count Number of failed proxy requests with this error reason.

List stats

List the proxy stats within a time period. The stats are a aggregated hourly. Hours without proxy usage do not have a proxy stat object.

This API endpoint is not paginated.

List stats

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/stats/", {
      "timestamp__lte":"2022-09-09T23:34:00.095501-07:00",
      "timestamp__gte":"2022-08-09T23:34:00.095501-07:00"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/stats/?timestamp__lte=2022-09-09T23:34:00.095501-07:00&timestamp__gte=2022-08-09T23:34:00.095501-07:00" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

[
  {
    "timestamp": "2022-08-11T17:00:00-07:00",
    "is_projected": false,
    "bandwidth_total": 5000,
    "bandwidth_average": 1000,
    "requests_total": 5,
    "requests_successful": 4,
    "requests_failed": 1,
    "error_reasons": [
      {
        "reason": "client_connect_forbidden_host",
        "type": "configuration",
        "how_to_fix": "The target website you are connecting cannot be accessed via Webshare Proxy.",
        "http_status": 403,
        "count": 1
      }
    ],
    "countries_used": {
      "GB": 1,
      "FR": 4
    },
    "number_of_proxies_used": 2,
    "protocols_used": {
      "http": 5
    },
    "average_concurrency": 0.0001388888888888889,
    "average_rps": 0.0002777777777777778,
    "last_request_sent_at": "2022-08-11T17:12:32.589667-07:00"
  },
  ...
]

HTTP Request

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

Parameter Description
timestamp__lte The timestamp of the stats will be less than this. If given a date in the future, projected stats will be included for each hour between now and the given date. Cannot be after the subscription.end_date. Default is subscription.end_date.
timestamp__gte The timestamp of the stats will be greater than this. Must be before the timestamp__lte field. Cannot be older than 90 days from today. Default is subscription.start_date.

Aggregate stats

Aggregate the proxy stats for the given period. Useful for showing the total proxy use in the subscription period.

Aggregate stats

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/stats/aggregate/", {
      "timestamp__lte":"2022-09-09T23:34:00.095501-07:00",
      "timestamp__gte":"2022-08-09T23:34:00.095501-07:00"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/stats/aggregate/?timestamp__lte=2022-09-09T23:34:00.095501-07:00&timestamp__gte=2022-08-09T23:34:00.095501-07:00" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "bandwidth_projected": 100000,
  "bandwidth_total": 5000,
  "bandwidth_average": 1000,
  "requests_total": 5,
  "requests_successful": 4,
  "requests_failed": 1,
  "error_reasons": [
    {
      "reason": "client_connect_forbidden_host",
      "type": "configuration",
      "how_to_fix": "The target website you are connecting cannot be accessed via Webshare Proxy.",
      "http_status": 403,
      "count": 1
    }
  ],
  "countries_used": {
    "GB": 1,
    "FR": 4
  },
  "number_of_proxies_used": 2,
  "protocols_used": {
    "http": 5
  },
  "average_concurrency": 0.0001388888888888889,
  "average_rps": 0.0002777777777777778,
  "last_request_sent_at": "2022-08-11T17:12:32.589667-07:00"
}

HTTP Request

Parameter Description
timestamp__lte The timestamp of the stats will be less than this. If given a date in the future, projected stats will be included for each hour between now and the given date. Cannot be after the subscription.end_date.
timestamp__gte The timestamp of the stats will be greater than this. Must be before the timestamp__lte field. Cannot be older than 90 days from today.

The proxy activity object

A new proxy activity is created for all proxy requests which are successfully authenticated through Webshare Proxy.

The proxy activity object

{
  "timestamp": "2022-08-16T15:29:42.517523-07:00",
  "protocol": "http",
  "request_duration": 0.5,
  "handshake_duration": 0.3,
  "tunnel_duration": 0.2,
  "error_reason": "client_connect_forbidden_host",
  "error_reason_how_to_fix": "The target website you are connecting cannot be accessed via Webshare Proxy.",
  "auth_username": null,
  "proxy_address": "192.168.5.1",
  "bytes": 0,
  "client_address": "10.1.0.1",
  "ip_address": "10.1.0.2",
  "hostname": "ipv4.webshare.io",
  "domain": "webshare.io",
  "port": 443,
  "proxy_port": null,
  "listen_address": "192.168.5.24",
  "listen_port": 6455
}

The proxy stats object attributes

Attributes Description
timestamp The timestamp of the proxy request. ISO 8601 format.
protocol Indicates the proxy protocol. Can be http or socks.
request_duration Total proxy request duration in seconds.
handshake_duration Total duration to authenticate and establish a proxy connection in seconds. You can consider this time as the overhead of proxy connection.
tunnel_duration Total duration in seconds the proxy connection stayed active after handshake was completed. May be null.
error_reason Error reason for the proxy request. May be null.
error_reason_how_to_fix User-friendly explanation on how to fix this error. May be null.
auth_username The proxy username used for this proxy request. Only set if error_reason=no_proxies_allocated. May be null.
proxy_address The IP address of the proxy use to access to the target site. For backbone proxy, this address would correspond to assigned IP address. May be null.
bytes Number of bytes consumed by this proxy request. Calculated by summing up all downloaded and uploaded data.
client_address The IP address you have used to connect to the proxy server.
ip_address The IP address of the target site. May be null.
hostname The hostname of the target site. May be null.
domain The domain name of the target site. May be null.
port The port the target site. May be null.
proxy_port The source port used to connect to the target site. May be null.
listen_address The IP address of the proxy server you have connected to. If you have used the Direct Connection mode, this field will be equal to the proxy_address. Otherwise, this field will be the IP address of p.webshare.io.
listen_port The port of the proxy server you have connected to.

List proxy activity

List the proxy activity within a time period.

You can paginate this endpoint using the starting_after and page_size fields instead of the page field. You can pass the timestamp of the latest activity instance to the starting_after queryset to view the next page.

List proxy activity

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/proxy/activity/", {
      "timestamp__lte":"2022-09-09T23:34:00.095501-07:00",
      "timestamp__gte":"2022-08-09T23:34:00.095501-07:00"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/activity/?timestamp__lte=2022-09-09T23:34:00.095501-07:00&timestamp__gte=2022-08-09T23:34:00.095501-07:00" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "count": 10,
  "next": null,
  "previous": null,
  "results": [
    {
      "timestamp": "2022-08-16T15:29:42.517523-07:00",
      "protocol": "http",
      "request_duration": 0.5,
      "handshake_duration": 0.3,
      "tunnel_duration": 0.2,
      "error_reason": "client_connect_forbidden_host",
      "error_reason_how_to_fix": "The target website you are connecting cannot be accessed via Webshare Proxy.",
      "auth_username": null,
      "proxy_address": "192.168.5.1",
      "bytes": 0,
      "client_address": "10.1.0.1",
      "ip_address": "10.1.0.2",
      "hostname": "ipv4.webshare.io",
      "domain": "webshare.io",
      "port": 443,
      "proxy_port": null,
      "listen_address": "192.168.5.24",
      "listen_port": 6455
    },
    ...
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/proxy/activity/

Parameter Description
timestamp__lte The timestamp of the stats will be less than this. If given a date in the future, projected stats will be included for each hour between now and the given date. Cannot be after the subscription.end_date. Default is six days ago.
timestamp__gte The timestamp of the stats will be greater than this. Must be before the timestamp__lte field. Cannot be older than 90 days from today. Default is now.
search Generic search query.
error_reason Match only requests with the given error_reason. You can pass * to filter for only requests with an error.
starting_after You can pass the timestamp of the last proxy activity to retrieve the next page.
bytes__gte Filter requests with bytes equal or greater than the given value.
bytes__lte Filter requests with bytes equal or less than the given value.

Subscription

Each Webshare account has 1 subscription and 1 active plan associated with it. There may be multiple in-active plans.

Subscription object holds general information about the user subscription (e.g. start/end dates). Plan object holds information about the customization options for the plan (e.g. plan type, monthly price, proxy locations).

Important distinction between Subscription and Plan is that Subscription stays with the user even after a user switches to a new Plan. Whereas, a new Plan object is created each time a customer re-customizes their Plan.

The subscription object

The subscription object

{ 
  "id": 1,
  "plan": 2,
  "payment_method": 1,
  "free_credits": 13.37,
  "term": "monthly",
  "start_date": "2022-06-14T11:19:14.489458-07:00",
  "end_date": "2022-07-14T11:19:14.489461-07:00",
  "renewals_paid": 0,
  "failed_payment_times": 0,
  "account_discount_percentage": 0,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}
Attributes Description
id Unique identifier of the subscription instance. This ID should not change for the user
plan Unique identifier of the active plan instance. This ID will change whenever a user re-customizes their plan
payment_method Unique identifier of the payment method
free_credits Free credits available in for the account in USD
term Used to determine the amount to charge in the next renewal. Can be monthly or yearly.
start_date The start date of the current renewal term. The difference between end/start dates are always 30 days even in yearly subscriptions.
end_date The end date of the current renewal term. The difference between end/start dates are always 30 days even in yearly subscriptions.
renewals_paid Number of 30 day increment renewals paid. yearly terms pay for 12 renewals at once while monthly terms pay for 1 renewal at a time.
failed_payment_times Number of times an automated renewal payment failed.
account_discount_percentage Discount percentage for the account. 0 means no discount. 30 means all prices are 30% discounted.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this instance was last updated.

The plan object

The plan object

{
  "id": 2,
  "bandwidth_limit": 50.0,
  "monthly_price": 9.99,
  "yearly_price": 49.99,
  "proxy_type": "shared",
  "proxy_subtype": "default",
  "proxy_count": 1000,
  "proxy_countries": {"ZZ": 1000},
  "on_demand_refreshes_total": 0,
  "on_demand_refreshes_used": 0,
  "on_demand_refreshes_available": 0,
  "automatic_refresh_frequency": 0,
  "automatic_refresh_last_at": null,
  "automatic_refresh_next_at": null,
  "proxy_replacements_total": 10,
  "proxy_replacements_used": 0,
  "proxy_replacements_available": 10,
  "subusers_total": 3,
  "subusers_used": 0,
  "subusers_available": 3,
  "is_unlimited_ip_authorizations": true,
  "is_high_concurrency": true,
  "is_high_priority_network": false,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}   
Attributes Description
id Unique identifier of the plan instance.
bandwidth_limit Bandwidth limit in GBs. 0 means unlimited bandwidth.
monthly_price Price in USD for the monthly term.
yearly_price Price in USD for the yearly term.
proxy_type Category of proxies. Options are: free, shared, semidedicated and dedicated.
proxy_subtype Sub category of the proxies. Options are default, non-premium, premium and isp. Not all proxy types have the same sub types.
proxy_count Number of proxies in the plan.
proxy_countries Number of proxies from each country code. ZZ means country is randomly allocated.
on_demand_refreshes_total Number of on-demand refreshes purchased as part of this plan.
on_demand_refreshes_used Number of on-demand refreshes used since subscription start date. The on-demand refreshes reset at the end of subscription end date.
on_demand_refreshes_available Number of on-demand refreshes available for this plan.
automatic_refresh_frequency Auto-refresh 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.
proxy_replacements_total Individual proxy replacements purchased as part of this plan.
proxy_replacements_used Individual proxy replacements used since subscription start date. The proxy replacements reset at the end of subscription end date.
proxy_replacements_available Individual proxy replacements available for this plan.
subusers_total Number of subusers allowed in this plan.
subusers_used Number of subusers currently active in this plan. Sub-users don't reset at the end of the subscription term.
subusers_available Number of subusers available in this plan.
is_unlimited_ip_authorizations Indicates if unlimited number of IP Authorizations can be created. If set to false, only 1 IP Authorization ca be created for each account.
is_high_concurrency Indicates whether high proxy concurrency is enabled for the account.
is_high_priority_network Indicates whether high proxy priority is enabled for the account.
created_at Timestamp on when the account was created
updated_at The timestamp when this instance was last updated.

List plans

This endpoint retrieves all plans created by the user (even the non-active ones) in paginated format with filtering & ordering enabled.

import requests

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

The above command returns JSON structured like this:

{  
   "count":1,
   "next":null,
   "previous":null,
   "results":[
     {
       "id": 2,
       "bandwidth_limit": 50.0,
       "monthly_price": 9.99,
       "yearly_price": 49.99,
       "proxy_type": "shared",
       "proxy_subtype": "default",
       "proxy_count": 1000,
       "proxy_countries": {"ZZ": 1000},
       "on_demand_refreshes_total": 0,
       "on_demand_refreshes_used": 0,
       "on_demand_refreshes_available": 0,
       "automatic_refresh_frequency": 0,
       "automatic_refresh_last_at": null,
       "automatic_refresh_next_at": null,
       "proxy_replacements_total": 10,
       "proxy_replacements_used": 0,
       "proxy_replacements_available": 10,
       "subusers_total": 3,
       "subusers_used": 0,
       "subusers_available": 3,
       "is_unlimited_ip_authorizations": true,
       "is_high_concurrency": true,
       "is_high_priority_network": false,
       "created_at": "2022-06-14T11:58:10.246406-07:00",
       "updated_at": "2022-06-14T11:58:10.246406-07:00"
     }
   ]
}

HTTP Request

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

Retrieve subscription

This endpoint returns the subscription object associated with the account. There is only 1 subscription associated with each account.

Retrieve subscription

import requests

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

the above command returns JSON structured like this:

{
  "id": 1,
  "plan": 2,
  "payment_method": 1,
  "free_credits": 13.37,
  "term": "monthly",
  "start_date": "2022-06-14T11:19:14.489458-07:00",
  "end_date": "2022-07-14T11:19:14.489461-07:00",
  "renewals_paid": 0,
  "failed_payment_times": 0,
  "account_discount_percentage": 0,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

Retrieve plan

This endpoint returns the plan. You can find the active plan id from the subscription object.

Retrieve plan

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/subscription/plan/2/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/subscription/plan/2/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "id": 2,
  "bandwidth_limit": 50.0,
  "monthly_price": 9.99,
  "yearly_price": 49.99,
  "proxy_type": "shared",
  "proxy_subtype": "default",
  "proxy_count": 1000,
  "proxy_countries": {"ZZ": 1000},
  "on_demand_refreshes_total": 0,
  "on_demand_refreshes_used": 0,
  "on_demand_refreshes_available": 0,
  "automatic_refresh_frequency": 0,
  "automatic_refresh_last_at": null,
  "automatic_refresh_next_at": null,
  "proxy_replacements_total": 10,
  "proxy_replacements_used": 0,
  "proxy_replacements_available": 10,
  "subusers_total": 3,
  "subusers_used": 0,
  "subusers_available": 3,
  "is_unlimited_ip_authorizations": true,
  "is_high_concurrency": true,
  "is_high_priority_network": false,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

GET https://proxy.webshare.io/api/v2/subscription/plan/<ID>/

URL Parameters

Parameter Description
ID The ID of the plan to retrieve

Subscription customization options

This endpoint returns the limits/options available to customize for a plan. This endpoint JSON encodes the entire request in the query GET parameter. Make sure the GET parameters are also URL encoded (as required by the HTTP standards).

Retrieve options

import requests
import json

response = requests.get(
    "https://proxy.webshare.io/api/v2/subscription/customize/",
    {
        "query": json.dumps(
            {
                "proxy_type": "shared",
                "proxy_subtype": "default",
                "proxy_countries": {"ZZ": 100},
            }
        )
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/subscription/customize/ \
  --data-urlencode "query={\"proxy_type\": \"shared\", \"proxy_subtype\": \"default\", \"proxy_countries\": {\"ZZ\": 100}}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "proxy_type": "shared",
  "proxy_subtype": "default",
  "proxy_count_max": 60000,
  "proxy_count_min": 1,
  "available_countries": {"US": 45000, "GB": 5000, "FR": 10000},
  "on_demand_refreshes_max": 1000,
  "on_demand_refreshes_min": 0,
  "automatic_refresh_frequency_max": 2592000,
  "automatic_refresh_frequency_min": 60,
  "proxy_replacements_max": 100000,
  "proxy_replacements_min": 0,
  "bandwidth_limit_max": 10000,
  "bandwidth_limit_min": 250,
  "subusers_max": 10000,
  "subusers_min": 3,
  "available_features": [
    {"feature": "is_unlimited_ip_authorizations"},
    {"feature": "is_high_concurrency"},
    {"feature": "is_high_priority_network"}
  ],
  "terms": [
    {"term": "monthly", "renewals_paid": 1},
    {"term": "yearly", "renewals_paid": 12}
  ]
}

HTTP Request

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

Parameter Description
proxy_type Category of proxies. Options are: free, shared, semidedicated and dedicated.
proxy_subtype Sub category of the proxies. Options are default, non-premium, premium and isp. Not all proxy types have the same sub types.
proxy_countries Number of proxies from each country code. ZZ means country is randomly allocated. Other customizations are based on this field.

Subscription pricing

This endpoint returns the pricing for a custom plan. This endpoint JSON encodes the entire request in the query GET parameter. Make sure the GET parameters are also URL encoded (as required by the HTTP standards).

HTTP Request

GET https://proxy.webshare.io/api/v2/subscription/pricing/?query={json_encoded}

JSON encode all the parameters below into the query GET query.

Parameter Description
proxy_type Category of proxies. Options are: free, shared, semidedicated and dedicated.
proxy_subtype Sub category of the proxies. Options are default, non-premium, premium and isp. Not all proxy types have the same sub types.
proxy_countries Number of proxies from each country code. ZZ means country is randomly allocated.
bandwidth_limit Bandwidth limit in GBs. 0 means unlimited bandwidth.
on_demand_refreshes_total Number of on-demand refreshes purchased as part of this plan.
automatic_refresh_frequency Auto-refresh your proxy list every automatic_refresh_frequency seconds. 0 value means no automatic refreshes.
proxy_replacements_total Individual proxy replacements purchased as part of this plan.
subusers_total Number of subusers allowed in this plan.
is_unlimited_ip_authorizations Indicates if unlimited number of IP Authorizations can be created. If set to false, only 1 IP Authorization ca be created for each account.
is_high_concurrency Indicates whether high proxy concurrency is enabled for the account.
is_high_priority_network Indicates whether high proxy priority is enabled for the account.
term Used to determine the amount to charge in the next renewal. Can be monthly or yearly.

Get Pricing

import requests
import json

response = requests.get(
    "https://proxy.webshare.io/api/v2/subscription/pricing/",
    {
        "query": json.dumps(
            {
                "proxy_type": "shared",
                "proxy_subtype": "default",
                "proxy_countries": {"US": 100},
                "bandwidth_limit": 5000,
                "on_demand_refreshes_total": 0,
                "automatic_refresh_frequency": 0,
                "proxy_replacements_total": 0,
                "subusers_total": 3,
                "term": "monthly",
                "is_unlimited_ip_authorizations": False,
                "is_high_concurrency": False,
                "is_high_priority_network": False,
            }
        )
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/subscription/pricing/" \
  --data-urlencode "query={\"proxy_type\": \"shared\", \"proxy_subtype\": \"default\", \"proxy_countries\": {\"US\": 100}, \"bandwidth_limit\": 5000, \"on_demand_refreshes_total\": 0, \"automatic_refresh_frequency\": 0, \"proxy_replacements_total\": 0, \"subusers_total\": 3, \"term\": \"monthly\", \"is_unlimited_ip_authorizations\": false, \"is_high_concurrency\": false, \"is_high_priority_network\": false}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

``

the above command returns JSON structured like this:

{
  "discount_percentage": 10,
  "non_discounted_price": 15.49,
  "price": 13.94,
  "paid_today": 8.94,
  "credits_added": 0,
  "credits_used": 5.00,
  "proxy_count_discount_tiers": [
    {"from": 0, "to": 250, "discount_percentage": 0, "per_proxy_price": 0.0299},
    {"from": 250, "to": 500, "discount_percentage": 5, "per_proxy_price": 0.028405},
    {"from": 500, "to": 1000, "discount_percentage": 10, "per_proxy_price": 0.02691},
    {"from": 1000, "to": 2500, "discount_percentage": 15, "per_proxy_price": 0.025415},
    {"from": 2500, "to": 5000, "discount_percentage": 20, "per_proxy_price": 0.02392},
    {"from": 5000, "to": 10000, "discount_percentage": 25, "per_proxy_price": 0.022425},
    {"from": 10000, "to": 25000, "discount_percentage": 30, "per_proxy_price": 0.020929999999999997},
    {"from": 25000, "to": null, "discount_percentage": 35, "per_proxy_price": 0.019435}
  ]
}

Response Format

Attributes Description
discount_percentage Percentage of discount applied to the final price.
non_discounted_price Original price for the term before any discounts are applied.
price The price after discounts are applied.
paid_today The amount which needs to be paid today. Credits are applied to this price.
credits_added Amount of credits added to the plan to make this subscription change. If changing from $50 plan to $100 plan, this field will be $50 (minus any deductions).
credits_used The total credits used to change the subscription.
proxy_count_discount_tiers List of discount percentages and per_proxy_price. From is exclusive; to is inclusive. E.g. 250 proxies have 0% discount, 251 proxies have 5% discount. If to is set to null, include up to infinity.

Purchase a plan

You can use this API to purchase a new plan. A new plan will override your existing plan and update your subscription.start_date.

The purchase API uses the same parameters as the Subscription pricing endpoint with 2 additional fields: payment_method and recaptcha.

Purchase plan

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/subscription/checkout/purchase/",
    json={
        "proxy_type": "shared",
        "proxy_subtype": "default",
        "proxy_countries": {"US": 100},
        "bandwidth_limit": 5000,
        "on_demand_refreshes_total": 0,
        "automatic_refresh_frequency": 0,
        "proxy_replacements_total": 0,
        "subusers_total": 3,
        "is_unlimited_ip_authorizations": False,
        "is_high_concurrency": False,
        "is_high_priority_network": False,
        "term": "monthly",
        "payment_method": 3,
        "recaptcha": "...",
    },
    headers={"Authorization": "Token APIKEY"},
)
response.json()
curl "https://proxy.webshare.io/api/v2/subscription/checkout/purchase/" \
  -X POST \
  -d "{\"proxy_type\": \"shared\", \"proxy_subtype\": \"default\", \"proxy_countries\": {\"US\": 100}, \"bandwidth_limit\": 5000, \"on_demand_refreshes_total\": 0, \"automatic_refresh_frequency\": 0, \"proxy_replacements_total\": 0, \"subusers_total\": 3, \"term\": \"monthly\", \"is_unlimited_ip_authorizations\": false, \"is_high_concurrency\": false, \"is_high_priority_network\": false, \"payment_method\": 3}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "payment_required": true,
  "plan": 2,

  "pending_payment": 3,
  "stripe_client_secret": "...",
  "stripe_payment_intent": "...",
  "stripe_payment_method": "..."
}

HTTP Request

POST https://proxy.webshare.io/api/v2/subscription/checkout/purchase/

The purchase API uses the same parameters as the Subscription pricing endpoint with 1 additional field: payment_method.

Parameter Description
payment_method Can be 3 unique options. 1) null, use the payment on file (same as subscription.payment_method). 2) Use an existing PaymentMethod id. 3) Add a new payment by using Stripe PaymentMethod ID (usually starts with "pm_...").
recaptcha The recaptcha token (can be invisible recaptcha).

Response Fields

Attributes Description
payment_required Whether a user needs to complete additional steps for the payment or not. If false, the purchase is completed and user now has the new plan.
plan The ID of the new Plan object.
pending_payment The ID of the PendingPayment instance. Only present if payment_required == true.
stripe_client_secret The client_secret for the Stripe PaymentIntent. Only present if payment_required == true.
stripe_payment_intent The ID of the Stripe PaymentIntent. Only present if payment_required == true.
stripe_payment_method The ID of the Stripe PaymentMethod. Only present if payment_required == true.

Renew a plan

You can use this API to renew an existing plan. After renewal, you will receive additional subscription.renewals_paid.

Renew plan

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/subscription/checkout/renew/",
    json={
        "term": "monthly",
        "payment_method": 3,
        "recaptcha": "...",
    },
    headers={"Authorization": "Token APIKEY"},
)
response.json()
curl "https://proxy.webshare.io/api/v2/subscription/checkout/renew/" \
  -X POST \
  -d "{\"term\": \"monthly\", \"payment_method\": 3, \"recaptcha\": \"...\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "payment_required": true,
  "plan": 2,

  "pending_payment": 3,
  "stripe_client_secret": "...",
  "stripe_payment_intent": "...",
  "stripe_payment_method": "..."
}

HTTP Request

POST https://proxy.webshare.io/api/v2/subscription/checkout/renew/

Parameter Description
payment_method Can be 3 unique options. 1) null, use the payment on file (same as subscription.payment_method). 2) Use an existing PaymentMethod id. 3) Add a new payment by using Stripe PaymentMethod ID (usually starts with "pm_...").
term The term to renew. Can be yearly or monthly.
recaptcha The recaptcha token (can be invisible recaptcha).

Response Fields

Attributes Description
payment_required Whether a user needs to complete additional steps for the payment or not. If false, the purchase is completed and user now has the new plan.
plan The ID of the current Plan object.
pending_payment The ID of the PendingPayment instance. Only present if payment_required == true.
stripe_client_secret The client_secret for the Stripe PaymentIntent. Only present if payment_required == true.
stripe_payment_intent The ID of the Stripe PaymentIntent. Only present if payment_required == true.
stripe_payment_method The ID of the Stripe PaymentMethod. Only present if payment_required == true.

Payments & Billing

Webshare has 2 main objects for managing payment & billing:

The payment method object

The payment method currently is always a card type. There may be different types of payment methods in the future (e.g. PayPal).

The payment method object

{ 
  "id": 1,
  "brand": "visa",
  "last4": "4242",
  "name": null,
  "expiration_year": 2023,
  "expiration_month": 6,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}
Attributes Description
id Unique identifier of the payment method instance.
brand Brand of the card. Could be mastercard, amex, visa, diners club, jcb or `unionpay
last4 Last 4 digits of the card.
expiration_year Expiration year of the card.
expiration_month Expiration month of the card. 6 means June.
created_at The timestamp of when the payment method was created.

The transaction object

The transaction object

{ 
  "id": 1,
  "status": "completed",
  "payment_method": {
    "id": 1,
    "brand": "visa",
    "last4": "4242",
    "name": null,
    "expiration_year": 2023,
    "expiration_month": 6,
    "created_at": "2022-06-14T11:58:10.246406-07:00",
    "updated_at": "2022-06-14T11:58:10.246406-07:00"
  },
  "reason": "Upgraded from Free Plan to 100 Proxies with 250 GB bandwidth.",
  "amount": 1.0,
  "refund_amount": 0.0,
  "refund_date": null,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}
Attributes Description
id Unique identifier of the transaction instance.
status Status of the object. Can be completed or refunded. Partial refunds will show up as refunded.
payment_method Nested payment method instance.
reason The reason of this transaction.
amount The amount of the transaction in USD.
refund_amount The amount refunded in USD.
refund_date The date the last refund was issued. May be null if no refund was issued. If a user is refunded multiple times for the same transaction, only the last date will be shown.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this instance was last updated.

The billing information object

The billing information object

{
  "id": 1,
  "name": "Webshare Software",
  "address": "Lemon Ave",
  "billing_email": "incomingbills@webshare.io",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}  
Attributes Description
id Unique identifier of the billing information instance.
name Name for the invoices. Will appear on invoices. Can be a company name. Default is empty string.
address Address for the invoices. Will appear on invoices. Can be a corporate address. Default is empty string.
billing_email Email address for the invoices. Will appear on invoices. Default is empty string.
created_at Timestamp on when the account was created
updated_at The timestamp when this instance was last updated.

Pending payment object

The pending payment object

{
  "id": 1,
  "status": "pending",
  "failure_reason": null,
  "payment_method": 2,
  "plan": 2,
  "transaction": null,
  "is_renewal": false,
  "term": "monthly",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "completed_at": null
}
Attributes Description
id Unique identifier of the pending payment object.
status Current state of the pending payment. Can be pending, processing, successful or failed.
failure_reason Set to a user-friendly string if a status is failed. Default is null.
payment_method Unique identifier of the payment method instance.
plan Unique identifier of the plan object.
transaction Unique identifier of the transaction object. Only set if the status is successful.
is_renewal Whether the payment should be used to renew the subscription or immediately change it.
term Term of the payment. Can be monthly or yearly.
created_at The timestamp on when the pending payment was created
updated_at The timestamp when the pending payment was last updated.
completed_at The timestamp when the pending payment status became successful. null by default.

List payment methods

This endpoint retrieves all payment methods associated with the user in paginated format with filtering & ordering enabled.

import requests

response = requests.get("https://proxy.webshare.io/api/v2/payment/card/", headers={"Authorization": "Token APIKEY"})
response.json()
curl "https://proxy.webshare.io/api/v2/payment/card/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "count":1,
  "next":null,
  "previous":null,
  "results":[
    {
      "id": 1,
      "brand": "visa",
      "last4": "4242",
      "name": null,
      "expiration_year": 2023,
      "expiration_month": 6,
      "created_at": "2022-06-14T11:58:10.246406-07:00",
      "updated_at": "2022-06-14T11:58:10.246406-07:00"
    }
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/payment/card/

List transactions

This endpoint retrieves all transactions associated with the user in paginated format with filtering & ordering enabled.

import requests

response = requests.get("https://proxy.webshare.io/api/v2/payment/transaction/", headers={"Authorization": "Token APIKEY"})
response.json()
curl "https://proxy.webshare.io/api/v2/payment/transaction/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "count":1,
   "next":null,
   "previous":null,
   "results":[
     {
       "id": 1,
       "status": "completed",
       "payment_method": {
         "id": 1,
         "brand": "visa",
         "last4": "4242",
         "name": null,
         "expiration_year": 2023,
         "expiration_month": 6,
         "created_at": "2022-06-14T11:58:10.246406-07:00",
         "updated_at": "2022-06-14T11:58:10.246406-07:00"
       },
       "reason": "Upgraded from Free Plan to 100 Proxies with 250 GB bandwidth.",
       "amount": 1.0,
       "refund_amount": 0.0,
       "refund_date": null,
       "created_at": "2022-06-14T11:58:10.246406-07:00",
       "updated_at": "2022-06-14T11:58:10.246406-07:00"
     }
   ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/payment/transaction/

List pending payments

This endpoint retrieves all pending payments associated with the user in paginated format with filtering & ordering enabled.

import requests

response = requests.get("https://proxy.webshare.io/api/v2/payment/pending/", headers={"Authorization": "Token APIKEY"})
response.json()
curl "https://proxy.webshare.io/api/v2/payment/pending/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{  
   "count":1,
   "next":null,
   "previous":null,
   "results":[
     {
       "id": 1,
       "status": "pending",
       "failure_reason": null,
       "payment_method": 2,
       "plan": 2,
       "transaction": null,
       "is_renewal": false,
       "term": "monthly",
       "created_at": "2022-06-14T11:58:10.246406-07:00",
       "updated_at": "2022-06-14T11:58:10.246406-07:00",
       "completed_at": null
     }
   ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/payment/pending/

Retrieve payment method

This endpoint retrieves the payment method by ID. You can find the active payment method id from the subscription object.

Retrieve payment method

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/payment/card/1/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/payment/card/1/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "id": 1,
  "brand": "visa",
  "last4": "4242",
  "name": null,
  "expiration_year": 2023,
  "expiration_month": 6,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

GET https://proxy.webshare.io/api/v2/payment/card/1/

URL Parameters

Parameter Description
ID The ID of the payment method to retrieve

Retrieve transaction

This endpoint retrieves the transaction by ID.

Retrieve Plan

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/payment/transaction/1/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/payment/transaction/1/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "id": 1,
  "status": "completed",
  "payment_method": {
    "id": 1,
    "brand": "visa",
    "last4": "4242",
    "name": null,
    "expiration_year": 2023,
    "expiration_month": 6,
    "created_at": "2022-06-14T11:58:10.246406-07:00",
    "updated_at": "2022-06-14T11:58:10.246406-07:00"
  },
  "reason": "Upgraded from Free Plan to 100 Proxies with 250 GB bandwidth.",
  "amount": 1.0,
  "refund_amount": 0.0,
  "refund_date": null,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

GET https://proxy.webshare.io/api/v2/payment/transaction/<ID>/

URL Parameters

Parameter Description
ID The ID of the transaction to retrieve

Retrieve billing information

This endpoint returns the billing information object associated with the account. There is only 1 billing information associated with each account.

Retrieve billing information

import requests

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

the above command returns JSON structured like this:

{
  "id": 1,
  "name": "Webshare Software",
  "address": "Lemon Ave",
  "billing_email": "incomingbills@webshare.io",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
} 

HTTP Request

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

Retrieve pending payment

This endpoint returns the pending payment object.

Retrieve pending payment

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/payment/pending/<ID>/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/payment/pending/<ID>/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "id": 1,
  "status": "pending",
  "failure_reason": null,
  "payment_method": 2,
  "plan": 2,
  "transaction": null,
  "is_renewal": false,
  "term": "monthly",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "completed_at": null
}

HTTP Request

GET https://proxy.webshare.io/api/v2/payment/pending/<ID>/

URL Parameters

Parameter Description
ID The ID of the pending payment to retrieve.

Update billing information

This endpoint updates the billing information.

import requests

response = requests.patch(
    "https://proxy.webshare.io/api/v2/subscription/billing_info/",
    json={
        "name":"New Billing Name"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/subscription/billing_info/" \
  -X PATCH \
  -d "{\"name\": \"New Billing Name\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "New Billing Name",
  "address": "Lemon Ave",
  "billing_email": "incomingbills@webshare.io",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-15T11:58:10.246406-07:00"
} 

HTTP Request

PATCH https://proxy.webshare.io/api/v2/subscription/billing_info/

Process pending payment

This endpoint processes a pending payment. The status of the pending payment must be pending to process a payment.

A pending payment can be processed after the front-end completes the payment tasks.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/payment/pending/<ID>/process/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/payment/pending/<ID>/process/" \
  -X POST \
  -H "Authorization: Token APIKEY"

The above command returns the pending payment instance structured like this:

{
  "id": 1,
  "status": "processing",
  "failure_reason": null,
  "payment_method": 2,
  "plan": 2,
  "transaction": null,
  "is_renewal": false,
  "term": "monthly",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "completed_at": null
}

HTTP Request

POST https://proxy.webshare.io/api/v2/payment/pending/<ID>/process/

URL Parameters

Parameter Description
ID The ID of the pending payment to cancel.

Cancel pending payment

This endpoint cancels the pending payment. The status of the pending payment must be pending to cancel a payment.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/payment/pending/<ID>/cancel/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/payment/pending/<ID>/cancel/" \
  -X POST \
  -H "Authorization: Token APIKEY"

The above command returns the pending payment instance structured like this:

{
  "id": 1,
  "status": "failed",
  "failure_reason": "Cancelled by the user.",
  "payment_method": 2,
  "plan": 2,
  "transaction": null,
  "is_renewal": false,
  "term": "monthly",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "completed_at": null
}

HTTP Request

POST https://proxy.webshare.io/api/v2/payment/pending/<ID>/cancel/

URL Parameters

Parameter Description
ID The ID of the pending payment to cancel.

Referral & Affiliate

You can earn credits or payouts directly to your PayPal account by referring users to Webshare. Switching to affiliate program via the API indicates your consent for the additional affiliate agreement https://www.webshare.io/affiliate-agreement.

The referral config object

Referral config object indicates the current state of the referral system.

The referral config object

{
  "id": 1,
  "mode": "credits",
  "paypal_payout_email": null,
  "id_verification_required": false,
  "credits_earned": 0.0,
  "payouts_earned": 0.0,
  "earn_out_frequency": "7 00:00:00",
  "next_earn_out_date": "2022-06-14T11:58:10.246406-07:00",
  "minimum_earn_out_amount": 10,
  "referral_code": "78saf89712",
  "referral_url": "https://www.webshare.io/?referral_code=78saf89712",
  "referral_maximum_credits": 100,
  "referral_credit_ratio": 0.25,
  "referral_payment_pending_days": "30 00:00:00",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}
Attributes Description
id Unique identifier of the referral config instance. This ID should not change for the user.
mode Indicates whether the system is in payout or credits mode. Possible options are payout and credits. In payout mode, user can receive earn-out to their PayPal account.
paypal_payout_email May be null if mode is credits. Must be set if the mode is payout.
id_verification_required After an account is eligible for a payout, they must complete ID verification. ID verification is not required until payout conditions are met.
credits_earned Amount of USD earned and pending to be converted to account credits. These credits will be converted to Subscription.free_credits at the time of the next earn-out.
payouts_earned Amount of USD earned and pending to be earned out to PayPal account. These credits will be converted to Subscription.free_credits at the time of the next earn-out.
earn_out_frequency Frequency of earn-outs. Format is [DD] [HH:MM:SS].
next_earn_out_date Timestamp of the next earn-out. At this time the credits_earned and payouts_earned will be converted to account credits or sent to PayPal.
minimum_earn_out_amount Minimum USD need to be earned for the earn-out to be processed. For example, if credits_earned is $5.00 and minimum_earn_out_amount is $10.00, no earn-out will be processed.
referral_code Unique referral code of this user. User can navigate to any Webshare public page with referral_code={referral_code} GET query to set the referral code.
referral_url Example referral URL to the Webshare home page.
referral_maximum_credits Maximum amount of credits/payouts can be earned from a single referral.
referral_credit_ratio Ratio of credits/payouts earned from a referral purchase. For example, if referral_credit_ratio=0.25, and referral spends $100, user will earn $25.
referral_payment_pending_days Grace period for a referral credit/payouts to become available. During the pending period, if the payment is reversed, the credits will be reversed too.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this instance was last updated.

Retrieve referral config

Retrieve referral config

import requests

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

the above command returns JSON structured like this:

{
  "id": 1,
  "mode": "credits",
  "paypal_payout_email": null,
  "id_verification_required": false,
  "credits_earned": 0.0,
  "payouts_earned": 0.0,
  "earn_out_frequency": "7 00:00:00",
  "next_earn_out_date": "2022-06-14T11:58:10.246406-07:00",
  "minimum_earn_out_amount": 10,
  "referral_code": "78saf89712",
  "referral_url": "https://www.webshare.io/?referral_code=78saf89712",
  "referral_maximum_credits": 100,
  "referral_credit_ratio": 0.25,
  "referral_payment_pending_days": "30 00:00:00",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

Update referral config

This endpoint updates the referral config. Only updatable fields are mode and paypal_payout_email.

import requests

response = requests.patch(
    "https://proxy.webshare.io/api/v2/referral/config/",
    json={
        "mode":"earnout",
        "paypal_payout_email": "paypal@webshare.io"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/referral/config/" \
  -X PATCH \
  -d "{\"mode\": \"earnout\", \"paypal_payout_email\": \"paypal@webshare.io\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "mode": "earnout",
  "paypal_payout_email": "paypal@webshare.io",
  "id_verification_required": false,
  "credits_earned": 0.0,
  "payouts_earned": 0.0,
  "earn_out_frequency": "7 00:00:00",
  "next_earn_out_date": "2022-06-14T11:58:10.246406-07:00",
  "minimum_earn_out_amount": 10,
  "referral_code": "78saf89712",
  "referral_url": "https://www.webshare.io/?referral_code=78saf89712",
  "referral_maximum_credits": 100,
  "referral_credit_ratio": 0.25,
  "referral_payment_pending_days": "30 00:00:00",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-15T11:58:10.246406-07:00"
}

HTTP Request

PATCH https://proxy.webshare.io/api/v2/referral/config/

The referral credit object

Each time a referral spends money on Webshare, the user may earn referral credits. Each credit is tracked by the referral credit object.

The referral credit object

{
  "id": 1,
  "mode": "credits",
  "amount": 2.50,
  "status": "pending",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "reverted_at": null
}
Attributes Description
id Unique identifier of the referral credit instance.
mode Indicates whether the referral credit is in payout or credit mode. This mode cannot be changed.
amount Amount earned in USD.
status Status can be pending, available or reverted. A credit becomes available after ReferralConfig.referral_payment_pending_days period.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this instance was last updated.
reverted_at The timestamp when this credit was reverted. Is null if the status is not reverted.

List referral credits

This endpoint returns the referral credits in paginated format.

List referral credits

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/referral/credit/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/referral/credit/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "mode": "credits",
      "amount": 2.50,
      "status": "pending",
      "created_at": "2022-06-14T11:58:10.246406-07:00",
      "updated_at": "2022-06-14T11:58:10.246406-07:00",
      "reverted_at": null
    },
    ...
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/referral/credit/

Retrieve referral credit

This endpoint lets you retrieve a referral credit.

Retrieve referral credit

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/referral/credit/<ID>/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/referral/credit/<ID>/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "id": 1,
  "mode": "credits",
  "amount": 2.50,
  "status": "pending",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "reverted_at": null
}

HTTP Request

GET https://proxy.webshare.io/api/v2/referral/credit/<ID>/

Parameter Description
ID The ID of the referral credit to retrieve.

The earn out object

Whenever a user is rewarded credits/payouts from their pending balance (e.g. ReferralConfig.credits_earned), an earn out instance is created.

The earn out object

{
  "id": 1,
  "mode": "credits",
  "paypal_payout_email": null,
  "amount": 2.50,
  "status": "completed",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}
Attributes Description
id Unique identifier of the earn out instance.
mode Indicates whether the earn out is a payout or credit.
paypal_payout_email If mode is payout, indicates the PayPal email which received the funds.
amount Amount earned out in USD.
status Status can be processing, completed or failed.
created_at The timestamp of when this instance was created.
updated_at The timestamp when this instance was last updated.

List earn outs

This endpoint returns the earn outs in paginated format.

List earn outs

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/referral/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/referral/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "mode": "credits",
      "paypal_payout_email": null,
      "amount": 2.50,
      "status": "completed",
      "created_at": "2022-06-14T11:58:10.246406-07:00",
      "updated_at": "2022-06-14T11:58:10.246406-07:00"
    },
    ...
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/referral/

Retrieve earn out

This endpoint lets you retrieve an earn out.

Retrieve earn out

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/referral/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/referral/" \
  -H "Authorization: Token APIKEY"

the above command returns JSON structured like this:

{
  "id": 1,
  "mode": "credits",
  "paypal_payout_email": null,
  "amount": 2.50,
  "status": "completed",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

GET https://proxy.webshare.io/api/v2/referral/earnout/<ID>/

Parameter Description
ID The ID of the earn out object to retrieve.

Account Verification

Your Webshare account may require verification from time-to-time to continue operating. This section provides the API endpoints to check if a verification is required and submit evidence.

Furthermore, you can view the format of API responses you may receive in case an account is suspended.

The verification object

You can use the API to retrieve information about your account verifications

The user profile object

{
  "id": 1,
  "type": "acceptable_use_violation",
  "state": "inflow",
  "started_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "needs_evidence": false
}

User Profile Object

Attributes Description
id Unique identifier of the verification instance.
type The type of the verification. Can be acceptable_use_violation, abuse_report or fraudulent_payment.
state The current state of the verification. Can be inflow, successful_verification or failed_verification.
created_at The timestamp of when this verification started.
updated_at The timestamp when this instance was last updated.
needs_evidence Whether this verification requires evidence from the user.

List verifications

This endpoint returns the account verifications in paginated format.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/verification/flow/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/verification/flow/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "type": "acceptable_use_violation",
      "state": "inflow",
      "started_at": "2022-06-14T11:58:10.246406-07:00",
      "updated_at": "2022-06-14T11:58:10.246406-07:00",
      "needs_evidence": false
    },
    ...
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/verification/flow/

Retrieve verification

This endpoint lets you retrieve an account verification.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/verification/flow/<ID>/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/verification/flow/<ID>/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "type": "acceptable_use_violation",
  "state": "inflow",
  "started_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "needs_evidence": false
}

HTTP Request

GET https://proxy.webshare.io/api/v2/verification/flow/<ID>/

URL Parameters

Parameter Description
ID The ID of the verification object.

Submit evidence

This endpoint lets you submit evidence for a verification. The encoding for this API must be multipart/form-data. You cannot send JSON content to this API.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/verification/flow/<ID>/submit_evidence/",
    data={"explanation": "We use proxies to scrape pricing information from e-commerce websites."},
    files={"files":[open("evidence.jpg")]},
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/verification/flow/<ID>/submit_evidence/" \
  -F "explanation=We+use+proxies+to+scrape+pricing+information+from+e-commerce+websites.&files=@evidence.jpg" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1,
  "type": "acceptable_use_violation",
  "state": "inflow",
  "started_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "needs_evidence": false
}

HTTP Request

POST https://proxy.webshare.io/api/v2/verification/flow/<ID>/submit_evidence/

URL Parameters

Parameter Description
ID The ID of the verification object.
explanation The explanation submitted as part of the verification.
files List of files submitted as part of the verification.

Account Suspended

If your account is suspended, all API requests will start returning the 403 Forbidden status with the following error message.

403 Forbidden

{
  "detail": "Your account is suspended.", 
  "code": "account_suspended"
}

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-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_countries": {
      "ZZ":1000
    },
   "proxy_limit":10.0,
   "max_thread_count": 500,
   "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"
}

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

Create a user

Create a new user by setting label and bandwidth limit.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/subuser/",
    json={"label":"newcustomer", "proxy_limit": 10, "max_thread_count":500}, 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/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_countries": null,
   "proxy_limit":10.0,
   "max_thread_count": 500,
   "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/v2/subuser/

Get a user

This endpoint retrieves a specific user.

import requests

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

The above command returns JSON structured like this:

{  
   "id":7,
   "label":"Test User",
   "proxy_countries": {
      "ZZ":1000
    },
   "proxy_limit":10.0,
   "max_thread_count": 500,
   "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/v2/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/v2/subuser/", headers={"Authorization": "Token APIKEY"})
response.json()
curl "https://proxy.webshare.io/api/v2/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_countries": {
              "ZZ":1000
            },
           "proxy_limit":10.0,
           "max_thread_count": 500,
           "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/v2/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/v2/subuser/<ID>/",
    json={"label":"newlabel"}, 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/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_countries": {
      "ZZ":1000
    },
   "proxy_limit":10.0,
   "max_thread_count": 500,
   "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/v2/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/v2/subuser/<ID>/refresh/",
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/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":"Test User",
   "proxy_countries": {
      "ZZ":1000
    },
   "proxy_limit":10.0,
   "max_thread_count": 500,
   "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/v2/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/v2/subuser/<ID>/", headers={"Authorization": "Token APIKEY"})

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

URL Parameters

Parameter Description
ID The ID of the user to delete.

Masquerade as a user

Add the X-Subuser header to your API calls to retrieve data as that particular sub-user.

import requests

response = requests.get("https://proxy.webshare.io/api/v2/proxy/config/", headers={
    "Authorization": "Token APIKEY",
    "X-Subuser": "<User ID>"
})
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/config/" \
  -H "Authorization: Token APIKEY" \
  -H "X-Subuser: <User ID>"

The above command returns JSON structured like this:

{
  "id": 1,
  "state": "completed",
  "countries": {"US":5, "FR":100},
  "available_countries": {"US": 95},
  "unallocated_countries": {},
  "ip_ranges_24": {"10.1.1.0/24": 5, "10.1.3.0/24": 100},
  "ip_ranges_16": {"10.1.0.0/16": 105},
  "ip_ranges_8": {"10.0.0.0/24": 105},
  "available_ip_ranges_24": {"1.2.3.0/24": 100},
  "available_ip_ranges_16": {"1.2.3.0/24": 100},
  "available_ip_ranges_8": {"1.2.3.0/24": 100},
  "username": "username",
  "password": "password",
  "request_timeout": 86400,
  "request_idle_timeout": 900,
  "ip_authorization_country_codes": ["US", "FR"],
  "auto_replace_invalid_proxies": true,
  "auto_replace_low_country_confidence_proxies": false,
  "proxy_list_download_token": "aa87abbc...zz",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

URL Parameters

Parameter Description
Subuser ID The ID of the subuser you wish to masquerade as

API Keys

You can use the API keys to authorize your access. All API keys have the same permissions and full account access.

The API key object

Each API key has the following fields

The API key object

{
  "id": 1337,
  "key": "abc1234...zzz",
  "label": "server1 key",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

API Key Object

Attributes Description
id The unique ID of the API key.
key The 40 character alpha-numeric API key.
label The label for this API key. May be duplicate with other labels.
created_at The timestamp when this instance was created.
updated_at The timestamp when this instance was last updated.

Create API key

This endpoint lets you create an API Key.

import requests

response = requests.post(
    "https://proxy.webshare.io/api/v2/apikey/", 
    json={"label": "server1 key"},
    headers={"Authorization": "Token APIKEY"})
response.json()
curl "https://proxy.webshare.io/api/v2/apikey/" \
  -X POST \
  -d "{\"label\": \"server1 key\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1337,
  "key": "abc1234...zzz",
  "label": "server1 key",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

POST https://proxy.webshare.io/api/v2/apikey/

Create API Key request

Attributes Description
label The label to assign to this API key. May be duplicate with other labels.

List API keys

This endpoint returns the API keys in paginated format.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/apikey/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/apikey/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1337,
      "key": "abc1234...zzz",
      "label": "server1 key",
      "created_at": "2022-06-14T11:58:10.246406-07:00",
      "updated_at": "2022-06-14T11:58:10.246406-07:00"
    },
    ...
  ]
}

HTTP Request

GET https://proxy.webshare.io/api/v2/apikey/

Get API key

This endpoint lets you retrieve an API key.

import requests

response = requests.get(
    "https://proxy.webshare.io/api/v2/apikey/<ID>/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/apikey/<ID>/" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1337,
  "key": "abc1234...zzz",
  "label": "server1 key",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the API key to retrieve.

Update API key

This endpoint updates an API key

import requests

response = requests.patch(
    "https://proxy.webshare.io/api/v2/apikey/<ID>/",
    json={
        "label":"new label"
    },
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/apikey/<ID>/" \
  -X PATCH \
  -d "{\"label\": \"new label\"}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token APIKEY"

The above command returns JSON structured like this:

{
  "id": 1337,
  "key": "abc1234...zzz",
  "label": "new label",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

HTTP Request

PATCH https://proxy.webshare.io/api/v2/apikey/<ID>/

Delete API key

This endpoint lets you delete an API key.

import requests

response = requests.delete(
    "https://proxy.webshare.io/api/v2/apikey/<ID>/", 
    headers={"Authorization": "Token APIKEY"}
)
response.json()
curl "https://proxy.webshare.io/api/v2/apikey/<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/v2/apikey/<ID>/

URL Parameters

Parameter Description
ID The ID of the API key to delete.

Pagination

The Webshare API uses pagination on some of its resource endpoints. The following GET query parameters are used to determine the current page and the page_size.

Some APIs which has streaming activity may opt to use starting_after instead of the page field. In either case, the page_size field is available.

Request Parameters

You can add the request parameters as part of your URL.

GET Query Parameter Description
page_size Number of elements returned in a page. Default page size is 25 (Optional field).
page The current page to retrieve. Default page is 1 (Optional field).
starting_after The ID of the last element of the current page. Default is null which means the most recent items. (Optional field).

Response Format

Response is in JSON object format with the following fields.

Key Description
count Total number of elements which are paginated.
next Full URL to the next page API resource. If there is no next page, set to null.
previous Full URL to the previous page API resource. If there is no previous page, set to null. If a page is using starting_after for pagination, previous field will not be available.
results List of elements which are paginated. If page_size is 25, you can expect up to 25 elements in the results.

Example paginated request

import requests

response = requests.get("https://proxy.webshare.io/api/v2/proxy/list/?page=4&page_size=10")
response.json()
curl "https://proxy.webshare.io/api/v2/proxy/list/?page=4&page_size=10"

Example paginated response

{
  "count": 35,
  "next": null,
  "previous": "https://proxy.webshare.io/api/v2/proxy/list/?page=3&page_size=10",
  "results": [
    {},
    {},
    {},
    {},
    {}
  ]

}

Filtering & Ordering

The Webshare API uses filtering, search and ordering on list resource endpoints. The following GET query parameters are \ used to determine the ordering and filtering.

Ordering

You can order a list resource endpoint by some fields available in the instance object. For example, integer and date fields can be commonly used for ordering.

You can combine multiple ordering fields and change ASC/DESC order.

Request Parameters

You can add the request parameters as part of your URL.

GET Query Parameter Description
ordering Comma separated name of the fields. Default ordering is ascending. Minus indicates descending order

Example ordering request

import requests

response = requests.get("https://proxy.webshare.io/api/v2/payment/transaction/?ordering=status,-created_at")
response.json()
curl "https://proxy.webshare.io/api/payment/transaction/?ordering=status,-created_at"

Filtering

You can filter list resource endpoints by exact, greater than, less than and contains methods.

Example filtering request

import requests

response = requests.get("https://proxy.webshare.io/api/payment/transaction/?status=completed,refunded&amount__lt=1337")
response.json()
curl "https://proxy.webshare.io/api/v2/payment/transaction/?status=completed,refunded&amount__lt=1337"

You can perform text search on resource endpoints. Generally, only the text fields will be included as part of the search.

Example search request

import requests

response = requests.get("https://proxy.webshare.io/api/v2/payment/transaction/?search=Free")
response.json()
curl "https://proxy.webshare.io/api/v2/payment/transaction/?search=Free"
GET Query Parameter Description
search The text search parameter.

Rate Limits

The Webshare API uses rate limits for various endpoints.

API Name Rate
General API 180 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 authentication token is wrong. Re-login with your user credentials.
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.
5xx Server Error -- We had a problem with our server. We have been notified and working on fixing the issue. Try again later.