Residential Proxies

Find out everything about Oxylabs Residential Proxies, code examples, location targeting parameters, and troubleshooting resources.

Oxylabs Residential Proxies use real IP addresses provided by Internet Service Providers (ISPs) attached to physical devices globally. These proxies rotate automatically with every request and support fine-grained country, city, state, ZIP code, ASN, and session targeting.

Connecting via Whitelisted IPs? If you prefer authenticating via IP Whitelisting rather than username/password credentials, follow our IP whitelisting & subdomain auth guide.

Basic query

Our Residential Proxies support HTTP, HTTPS, HTTP/3 (MASQUE), and SOCKS5 protocols. You can learn more about using them here.

Making a basic request requires only passing your proxy user credentials (username and password) to the backconnect entry node (pr.oxylabs.io:7777). Each request automatically routes through a random IP address.

cURL

curl -x pr.oxylabs.io:7777 -U "customer-USERNAME:PASSWORD" https://ip.oxylabs.io/location

PHP

<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$proxy = 'pr.oxylabs.io:7777';
$query = curl_init('https://ip.oxylabs.io/location');
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;
?>

Python

import urllib.request

username = 'USERNAME'
password = 'PASSWORD'
entry = f'http://customer-{username}:{password}@pr.oxylabs.io:7777'

query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())

Java

package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}

C#

using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
c

Ruby

require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body

Example response

Testing your connection against https://ip.oxylabs.io/location returns data from MaxMind, IP2Location, DB-IP, and IPinfo.io. The parameters include IP address, provider, country, city, ZIP code, ASN, organization name, and time zone.

{
  "ip": "185.220.101.5",
  "provider": "Comcast Cable",
  "country": "United States",
  "country_code": "US",
  "city": "New York",
  "zip": "10001",
  "asn": 7018,
  "organization": "ATT-INTERNET4",
  "timezone": "America/New_York"
}

Customizing your requests

Once a basic connection is verified, customize your requests to suit your specific needs:

Location & geo-targeting	Apply country, city, state, continent, ZIP code, ASN, or coordinate parameters.
Session control	Sticky sessions (sessid), session durations (sesstime), single-IP binding (sessid_oneip), and sticky port ranges.
Protocols & ports	Configure HTTP, HTTPS, HTTP/3, and SOCKS5 connections.
Advanced filters	Target specific operating systems (platform) or IP protocol versions.
IP whitelisting	Connect without passwords using IP-based authentication.

Query parameters

A single backconnect proxy (pr.oxylabs.io:7777) allows you to customize your proxy via additional parameters in the username (geo-location, sticky sessions, etc.). Here is a sample of credentials with a breakdown:

Parameter	Type	Description
customer	Mandatory	Username string prefix (e.g., customer-USERNAME).
cc	Location	Case-insensitive 2-letter ISO 3166-1 country code (e.g., cc-DE, cc-US).
city	Location	English city name; requires cc (e.g., cc-US-city-los_angeles).
st	Location	US state name with us_ prefix (e.g., st-us_california).
cn	Location	2-letter continent code (e.g., cn-EU, cn-AS).
postalcode	Location	5-digit US ZIP code; requires cc-US (e.g., postalcode-90210).
ASN	Location	Autonomous System Number (e.g., ASN-21928).
geohash	Location	Target Geohash grid cells level 1–4 (e.g., geohash-u09 for Paris).
sessid	Session	Random string to maintain IP across requests (10-min default).
sesstime	Session	Extend session duration in minutes up to 1440 min (e.g., sesstime-30).
sessid_oneip	Session	Bind session strictly to single exit node; fails with 502 on drop.
platform	Filter	Target OS fingerprint (windows, macos, linux, android, ios).
ipversion	Filter	Restrict proxy pool to ipversion-4 or ipversion-6.

Common proxy string formats

Depending on your workflow, third-party software, or custom scripts, proxy credentials can be formatted in several ways:

Format	Use case
HOST:PORT:USER:PASS (pr.oxylabs.io:7777:customer-john:pass123)	Backconnect entry gateway format used in standard automation tools.
USER:PASS@HOST:PORT (customer-john:[e-mail]:7777)	Standard URI format used by cURL, Python requests, Node.js axios, etc.
IP:PORT:USER:PASS (185.220.101.5:8000:john:pass123)	Direct IP format commonly used in botting tools and desktop scrapers.
USER:PASS:IP:PORT (john:pass123:185.220.101.5:8000)	Reversed string format used by legacy tools requiring custom parsing.
IP:PORT (185.220.101.5:8000)	IP-whitelisted format (no username/password required).

Dashboard & account management

• Access your Oxylabs Dashboard to view real-time traffic usage, request statistics, and manage sub-users.
• Use the automated Endpoint Generator to generate and export custom proxy lists in cURL, Python, PHP, Node.js, GO, Java, or custom details for integrations.
• Manage sub-users and track usage programmatically via Public API.

Need technical assistance?

Contact your Account Manager or reach our 24/7 support team using one of the below:

• Live chat. Access live chat through your dashboard or on the Oxylabs website for quick questions or bug reports.
• Email. You can contact us via [e-mail]. We recommend this method for less urgent questions or suggestions.