Quick Start

Before we begin, please make sure you have received a username, password, and all URLs linking to your IP list from a Sales Representative, Dedicated Account Manager, or Support Team.

There are two ways you can get to your IP list. You can either access the IP list directly from your browser by opening the URL you received (e.g.: https://proxy.oxylabs.io/all). You will then be asked to enter your login credentials (HTTP Basic Auth).

Or you can retrieve the list by making a GET request to the URL you received (for example: https://proxy.oxylabs.io/all). Don't forget to replace USERNAME and PASSWORD with your proxy user credentials.

To make a request using a proxy, you will need to choose an IP address form the acquired list and specify it in the request parameters. You can see an example in cURL below. You can find more code samples in other languages here or full code examples on our GitHub.

If there are any questions we have not covered in this doccumentation, please contact your Dedicated Account Manager or our Support at support@oxylabs.io.

Proxy Lists

Basic

127.0.0.1:60000
127.0.0.2:60000
127.0.0.3:60000
127.0.0.4:60000

You should receive a URL to your proxy list from your Dedicated Account Manager or our Support and it should look something like this:

https://proxy.oxylabs.io/key/a27c5343ce4c4637a85a9297ddf1cace

Simply open this URL in your browser (or any other prefered software). You will then be asked to enter your login credentials (HTTP Basic Auth):

Once you do that, the list of proxies will be shown in a plain text.

If you have multiple lists and wish to get all IPs assigned to your account, you can use this URL:

https://proxy.oxylabs.io/all

You can also include ?showCountry or ?showCity at the end of your URL to get IPs with their corresponding locations.

RESTful

Showing All Available Proxy Lists

curl -u username:password "https://api.oxylabs.io/v1/proxies/lists"

import requests
requests.get('https://api.oxylabs.io/v1/proxies/lists', auth=('username', 'password'))

<?php
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.oxylabs.io/v1/proxies/lists");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_USERPWD, 'username:password');

$result = curl_exec($curl);
?>

using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy.Credentials = new NetworkCredential("username", "pass");
        Console.WriteLine(client.DownloadString("https://api.oxylabs.io/v1/proxies/lists"));
    }
}

Sample output:

[
  {
    "uuid": "123e4567-e89b-12d3-a456-426655440000",
    "key": "12345678",
    "updated_timestamp": "2016-09-28T13:03:50+0300",
    "ips_count": 2000,
    "href": "http://api.oxylabs.io/v1/proxies/lists/123e4567-e89b-12d3-a456-426655440000"
  }
]

With this endpoint, you can retrieve proxy lists that belong to your user:

Retrieving a Specific Proxy List

curl -u username:password "https://api.oxylabs.io/v1/proxies/lists/{uuid}"

import requests
requests.get('https://api.oxylabs.io/v1/proxies/lists/{uuid}', auth=('username', 'password'))

<?php
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.oxylabs.io/v1/proxies/lists/{uuid}");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_USERPWD, 'username:password');
?>

using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy.Credentials = new NetworkCredential("username", "pass");
        Console.WriteLine(client.DownloadString("https://api.oxylabs.io/v1/proxies/lists/{uuid}"));
    }
}

Sample output:

[
  {
    "ip": "127.0.0.1",
    "port": "60000",
    "country": "US"
  },
  { 
    "ip": "127.0.0.2",
    "port": "60000",
    "country": "GB"
  }
]

With this endpoint, you can retrieve a specific proxy list:

Request parameters:

Parameter	Description
uuid	The uuid of the proxy-list to retrieve

Making Requests

If you want to use Dedicated Datacenter Proxies via user/pass authentification method:

curl -x 1.2.3.4:60000 -U user1:pass1 http://ip.oxylabs.io 

import requests

response = requests.get(
    'http://ip.oxylabs.io',
    proxies={'http': 'http://user1:pass1@1.2.3.4:60000',
            'https': 'http://user1:pass1@1.2.3.4:60000'}
)
print(response.text)

<?php
    $username = 'USERNAME';
    $password = 'PASSWORD';
    $proxy = '1.2.3.4:60000';
    $query = curl_init('https://ip.oxylabs.io');
    curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
    curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username:$password");
    $output = curl_exec($query);
    curl_close($query);
    if ($output)
        echo $output;
?>

using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("1.2.3.4:60000");
        client.Proxy.Credentials = new NetworkCredential("username", "pass");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io"));
    }
}

If you want to use Dedicated Datacenter Proxies via Whitelisted IP authentification method:

curl -x 1.2.3.4:65432 http://ip.oxylabs.io 

import requests

response = requests.get(
    'http://ip.oxylabs.io',
    proxies={'http': 'http://1.2.3.4:65432',
            'https': 'http://1.2.3.4:65432'}
)
print(response.text)

<?php
    $username = 'USERNAME';
    $password = 'PASSWORD';
    $proxy = '1.2.3.4:65432';
    $query = curl_init('https://ip.oxylabs.io');
    curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
    curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username:$password");
    $output = curl_exec($query);
    curl_close($query);
    if ($output)
        echo $output;
?>

using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("1.2.3.4:65432");
        client.Proxy.Credentials = new NetworkCredential("username", "pass");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io"));
    }
}

By default, Oxylabs proxies and Proxy Rotator use a basic HTTP authentication that requires you to provide a username and password. You can get your credentials by contacting your Dedicated Account Manager or our Support Team at support@oxylabs.io.

We also support authentication based on whitelisted IP addresses. See Whitelisting IPs.

Depending on your authentication method, you might need to change the proxy port:

Proxy Port	Usage
60000	Required with proxies when login credentials are used (username and password). This port is used with proxy Proxy Rotator as well when used with both login credentials and whitelisted IPs.
65432	Required with proxies when authorization is done via whitelisted IPs.

Whitelisting IPs

Dashboard

We also support authentication based on an IP address. If you are using proxies directly (without proxy Proxy Rotator), you can whitelist your IPs by yourself. Just log into https://stats.oxylabs.io. Choose your preferred language - our dashboard is available in English and Chinese. Then, on the sidebar at the bottom you will see a section named "Add Whitelist". After clicking on the link you will be navigated to self-whitelist page which looks like this:

Here you can manage your whitelisted IPs that you can use to access proxies. You can whitelist individual IPs, as well as up to 24 subnets. If you would like to whitelist a larger subnet, please contact your Dedicated Account Manager or Support Team at support@oxylabs.io.

If you are using proxy Proxy Rotator or SOCKS proxies, you cannot whitelist your IP address by yourself. Instead, you will have to give us a list of IP address you want to use to connect to proxies. We will whitelist them (add them to firewall exception rules). After doing so, you will be able to access your proxies without login credentials.

Bear in mind, that if you are using whitelisted IPs to access your proxies, you will need to use port 65432. For proxy Proxy Rotator the port remains 60000.

RESTful

You can also whitelist IPs by sending queries directly to our endpoints. Please note there is a 5-minute cooldown for confirming any changes to your whitelisted IP list.

Getting Whitelisted IPs List

curl -u username:password "https://api.oxylabs.io/v1/whitelisted_ips"

import requests
requests.get('https://api.oxylabs.io/v1/whitelisted_ips', auth=('username', 'password'))

<?php
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.oxylabs.io/v1/whitelisted_ips");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_USERPWD, 'username:password');

$result = curl_exec($curl);
?>

Sample output:

{
    "data": [
        {
            "id": 9765,
            "address": "127.0.0.1"
        },
        {
            "id": 9766,
            "address": "127.0.0.2"
        }
    ]
}

Response	Description
200	Success. Response body contains all currently whitelisted IPs and their ids.

Adding a Whitelisted IP

curl -X POST -u username:password "https://api.oxylabs.io/v1/whitelisted_ips"
--header "Content-Type: application/json" --data '{"address": "127.0.0.1"}'

import requests
requests.post('https://api.oxylabs.io/v1/whitelisted_ips',
              headers={"Content-Type": "application/json"},
              data={"address": "127.0.0.1"}
              auth=('username', 'password'))

<?php
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.oxylabs.io/v1/whitelisted_ips");
$payload = json_encode( array( "address"=> "127.0.0.1" ) );
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt( $ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_USERPWD, 'username:password');

$result = curl_exec($curl);
?>

Response	Description
201	Success. The IP address has been added to the list. Response body contains the newly added address and id.
422	Error. Request body contains an invalid IP address. Response body contains the error message.

{
    "error": {
        "message": "This is not a valid IP address.",
        "code": 422
    }
}

Sample output:

{
    "id": 9767,
    "address": "127.0.0.1"
}

Removing a Whitelisted IP

curl -X DELETE -u username:password "https://api.oxylabs.io/v1/whitelisted_ips/{id}"

import requests
requests.delete('https://api.oxylabs.io/v1/whitelisted_ips/{id}', auth=('username', 'password'))

<?php
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.oxylabs.io/v1/whitelisted_ips/{id}");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_USERPWD, 'username:password');

$result = curl_exec($curl);
?>

Parameter	Description
id	The id of the IP address you want to delete (you can get it from GET whitelisted IPs endpoint)

Response	Description
204	Success. The IP address has been removed from the list. Response body is empty.
403	Error. Request contains an invalid id. Response body contains the error message "Access Denied".

Saving Changes (5min Cooldown)

curl -X POST -u username:password "https://api.oxylabs.io/v1/whitelisted_ips/upload_to_servers"

import requests
requests.delete("https://api.oxylabs.io/v1/whitelisted_ips/upload_to_servers", auth=('username', 'password'))

<?php
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://api.oxylabs.io/v1/whitelisted_ips/upload_to_servers");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_USERPWD, 'username:password');

$result = curl_exec($curl);
?>

Response	Description
202	Success. Changes to your whitelisted IP list have been confirmed. Response body is empty.
429	Error. Changes have not been confirmed, the endpoint is on a 5 minute cooldown. Response body contains the error message "You have exceed the rate limit for the endpoint. Please try again later"

Dedicated Datacenter Proxy API

Managing IPs

To manage your proxies via Dedicated Datacenter Proxy API, please refer to this documentation in OpenAPI format. The API allows you to add or replace proxy subnets in your proxy lists. API also lets you see the statuses of the initiated replacement or addition processes and see historical changes with new and replaced proxies. Acquire the proxy list UUID and modify your proxy lists at any time by referring to the API.

Checking offline IPs

Dedicated Datacenter Proxy API allows users to get IP adresses from their lists that are currently offline. Subnets endpoint will return a list of IPs that are currently offline due to ongoing downtime. IPs included in this list are automatically included in our recovery processes and they will become online ASAP. This visibility lets users exclude offline IPs from their scraping operations to ensure high success rate or initiate replacement processes to minimise performance impact.

Proxy Rotator - Optional

curl --proxy vm.oxylabs.io:60000 http://ip.oxylabs.io

import requests

response = requests.get(
    'http://ip.oxylabs.io',
    proxies={'http': 'http://vm.oxylabs.io:60000',
            'https': 'http://vm.oxylabs.io:60000'}
)
print(response.text)

<?php
    $username = 'USERNAME';
    $password = 'PASSWORD';
    $proxy = 'http://vm.oxylabs.io:60000';
    $query = curl_init('https://ip.oxylabs.io');
    curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
    curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username:$password");
    $output = curl_exec($query);
    curl_close($query);
    if ($output)
        echo $output;
?>

using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("http://vm.oxylabs.io:60000");
        client.Proxy.Credentials = new NetworkCredential("username", "pass");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io"));
    }
}

This service is optional and is not included in subscription. Instead of connecting to individual IPs, we provide you with a single endpoint to your assigned proxy list. With every request, the endpoint fetches a different IP. To learn how to use the endpoint as a proxy, please see the example on the right.

Note: Proxy Rotator should be used only with port 60000.

Session Control Using Proxy Rotator

user1@machine:~$ curl -x vm.oxylabs.io:60000 -U user:pass http://ip.oxylabs.io --proxy-header "Proxy-Server: s10"
1.2.30.40
user1@machine:~$ curl -x vm.oxylabs.io:60000 -U user:pass http://ip.oxylabs.io --proxy-header "Proxy-Server: s10"
1.2.30.40
user1@machine:~$ curl -x vm.oxylabs.io:60000 -U user:pass http://ip.oxylabs.io --proxy-header "Proxy-Server: s10"
1.2.30.40

import requests

headers = { 
    "Proxy-Server": "s10"
}

response = requests.get(
    'http://ip.oxylabs.io',
    proxies={'http': 'http://vm.oxylabs.io:60000',
            'https': 'http://vm.oxylabs.io:60000'},
            headers=headers}
)
print(response.text)

<?php
    $username = 'USERNAME';
    $password = 'PASSWORD';
    $proxy = 'http://vm.oxylabs.io:60000';
    $query = curl_init('https://ip.oxylabs.io');
    curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
    curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username:$password");

    $headers = [
        "Proxy-Server: s10"
    ];
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $output = curl_exec($query);
    curl_close($query);
    if ($output)
        echo $output;
?>

using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("http://vm.oxylabs.io:60000");
        client.Proxy.Credentials = new NetworkCredential("username", "pass");

        client.Headers.Add("Proxy-Server", "s10");

        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io"));
    }
}

It is possible to keep the same IP address with the Proxy Rotator. Firstly, you will need to know how many proxies your Proxy Rotator has. Then simply add --proxy-header "Proxy-Server: sXXX" header to your request, where sXXX is the number of the proxy, for example, s5 or s2541.

Response Codes

Response	Error Message	Description
407	Proxy Authentication Required	You are accessing proxy through 60000 port, but you have not provided authorization header, or your credentials are incorrect.
504	Gateway Timeout	Proxy server timed out. Waiting for a response from the target server. Usually about 60s.
503	Service Unavailable	Failed to connect to the target server. DNS failure to resolve the target server address.
401	Unauthorized	Incorrect credentials.
404	Not Found	The resource specified could not be found.
500	Internal Server Error	We had a problem with our server. Try again later.

These are the most common response codes that you can get while using our Datacentre Proxies. If you receive any other response code, please get in touch with your Dedicated Account Manager for more information.

3rd Party Integrations

Oxylabs Proxy Manager

Oxylabs Proxy Manager is a proxy management extension for Chrome. It is not only free but also works with any proxy provider of your choice. Enable your proxy without having to jump through settings and menu options. Download the extension from Chrome Web Store here

• Click the extension icon to open the application

• If you haven't added any proxies yet, you will see Add new proxy button. Click it to continue.

• Add proxy profile. Provide a name for the profile under Enter name. Enter on of the proxies you have purchased from us as Proxy server IP and 60000 as Port if you are using username:password authentication method, and 65432 if you are using whitelisted IPs.

Fill in your Username and Password. Finally, click Save changes. If you have whitelisted your IP, you don't need to do this step at all.

• Open the extension and click Connect. That's it, you are now using dedicated datacenter proxies.

SwitchyOmega

SwitchyOmega is a powerful and reliable proxy manager that works with many popular browsers. From our own experience, it is one of the best proxy plugins out there. We highly recommend using SwitchyOmega with our proxies. To do that, you will need to get the plugin. For Chrome, click here, for Firefox click here. Once you have it installed, you should:

• Open Switchy Omega options.

• Click New profile....

• Give the new profile a name, choose Proxy Profile type and click Create

• Change Protocol to HTTP. Under Server enter one of the proxies you have purchased from us. Under Port add 60000 if you are using username:password authentication method, and 65432 if you are using whitelisted IPs.

• Next, click the lock button on the right. Fill in your Username and Password. Click Save changes.

If you have whitelisted your IP, you don't need to do this step at all.

• Click Apply changes

• For the final step, click on SwitchyOmega icon and choose your newly configured proxy. You are now ready to go!

FoxyProxy

FoxyProxy is a simple proxy manager that works with many popular browsers. First, you will need to get FoxyProxy. For Chrome, click here, for Firefox click here. Once you have it installed, you should:

• Open FoxyProxy Options.

• Click Add.

• In IP address, DNS name, server name fields enter one of the proxies.

• In Port field enter port. If you use user/pass authentication port is 60000. If you have whitelisted your IP the port is 65432.

• In Username (optional) field you should enter your username. If you have whitelisted your IP, leave this field blank as the plugin will authorize through it and ignore everything you write in this field.

• In Password (Optional) field you should enter your password. If you have whitelisted your IP and wish to authorise through it, leave this field blank.

• After filling in all fields press Save.

• In order to get all of your requests running through this setup, you must press on the FoxyProxy plugin icon (1) and click on Use proxy Proxy for all URLs (ignore patterns) (2).

(1)

(2)

• That is it, you are done!

Proxifier

To use Dedicated Datacenter Proxies with Proxfier, simply follow these steps:

• Open Proxifier app.

• Add proxies. Click on Proxies (1). Click Add(2).

• In the following window, enter the required information. IP Address(1), Port(2) which for the username/pass authentication is 60000 and for whitelisted IP authentication - 65432 , select HTTPS(3) protocol. In the authentication box click Enable(4) and enter provided Username(5) and Password(6). Do not forget to add customer- at the beginning of the username. If you have whitelisted your devices, do not click on Enable, your authenticiation will be done without username/password. If you wish, you can enable Appear as Web Browser option. Click OK.

• You will be asked Do you want Proxifier to use this proxy by default? This means that this setup will be used for all of your browsers. It is up to you to decide whether you want that or not. If you select Yes, you are done setting up. If you wish to use proxies just on a particular browser, follow these next steps.

• Click on Rules(1) and then click Add...(2).

• Click +(1) button to add applications that you want to use the proxy settings with. Select a browser that you want to use these proxy settings with and click on it. Finally, you have to change Action(2). Click on it and select your created proxy.

• That is it. Now all of your requests (while using a browser) will be made via proxies.