> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/proxies/residential-proxies.md).

# Residential Proxies

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

Oxylabs [**Residential Proxies**](https://oxylabs.io/products/residential-proxy-pool) 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.

{% hint style="info" %}
**Connecting via Whitelisted IPs?** If you prefer authenticating via IP Whitelisting rather than `username`/`password` credentials, follow our [IP whitelisting & subdomain auth guide](/products/proxies/residential-proxies/whitelisting-ips.md). 
{% endhint %}

## Basic query

{% hint style="info" %}
Our Residential Proxies support `HTTP`, `HTTPS`, `HTTP/3 (MASQUE)`, and `SOCKS5` protocols. You can learn more about using them [**here**](/products/proxies/residential-proxies/protocols.md).
{% endhint %}

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.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="PHP" %}

```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;
?>
```

{% endtab %}

{% tab title="Python" %}

```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())
```

{% endtab %}

{% tab title="Java" %}

```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);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
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
```

{% endtab %}

{% tab title="Ruby" %}

```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
```

{% endtab %}
{% endtabs %}

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

```json
{
  "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:

<table data-header-hidden><thead><tr><th width="216"></th><th></th></tr></thead><tbody><tr><td><a href="/products/proxies/residential-proxies/location-settings.md"><strong>Location &#x26; geo-targeting</strong></a></td><td>Apply country, city, state, continent, ZIP code, ASN, or coordinate parameters.</td></tr><tr><td><a href="/products/proxies/residential-proxies/session-control.md"><strong>Session control</strong></a></td><td>Sticky sessions (<code>sessid</code>), session durations (<code>sesstime</code>), single-IP binding (<code>sessid_oneip</code>), and sticky port ranges.</td></tr><tr><td><a href="/products/proxies/residential-proxies/protocols.md"><strong>Protocols &#x26; ports</strong></a></td><td>Configure <code>HTTP</code>, <code>HTTPS</code>, <code>HTTP/3</code>, and <code>SOCKS5</code> connections.</td></tr><tr><td><a href="/products/proxies/residential-proxies/advanced-filters.md"><strong>Advanced filters</strong></a></td><td>Target specific operating systems (<code>platform</code>) or IP protocol versions.</td></tr><tr><td><a href="/products/proxies/residential-proxies/whitelisting-ips.md"><strong>IP whitelisting</strong></a></td><td>Connect without passwords using IP-based authentication.</td></tr></tbody></table>

### 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:

<figure><img src="https://3826932121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-d3f1a59d25a42e887f472219825623641de0ef3b%2FCode%20explained%20for%20Resi%20documentation%20(upd%202025-06).png?alt=media" alt=""><figcaption></figcaption></figure>

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

### Common proxy string formats

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

<table><thead><tr><th width="359">Format</th><th>Use case</th></tr></thead><tbody><tr><td>HOST:PORT:USER:PASS<br>(<code>pr.oxylabs.io:7777:customer-john:pass123</code>)</td><td>Backconnect entry gateway format used in standard automation tools.</td></tr><tr><td>USER:PASS@HOST:PORT<br>(<code>customer-john:pass123@pr.oxylabs.io:7777</code>)</td><td>Standard URI format used by cURL, Python <code>requests</code>, Node.js <code>axios</code>, etc.</td></tr><tr><td>IP:PORT:USER:PASS<br>(<code>185.220.101.5:8000:john:pass123</code>)</td><td>Direct IP format commonly used in botting tools and desktop scrapers.</td></tr><tr><td>USER:PASS:IP:PORT<br>(<code>john:pass123:185.220.101.5:8000</code>)</td><td>Reversed string format used by legacy tools requiring custom parsing.</td></tr><tr><td>IP:PORT<br>(<code>185.220.101.5:8000</code>)</td><td>IP-whitelisted format (no username/password required).</td></tr></tbody></table>

## Dashboard & account management

* Access your [Oxylabs Dashboard](https://dashboard.oxylabs.io/en) to view real-time traffic usage, request statistics, and manage sub-users.
* Use the automated [Endpoint Generator](/products/proxies/residential-proxies/endpoint-generator.md) 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](/products/proxies/residential-proxies/public-api.md).

## Need technical assistance?

&#x20;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**](https://oxylabs.io/) for quick questions or bug reports.
* **Email**. You can contact us via [**support@oxylabs.io**](mailto:support@oxylabs.io). We recommend this method for less urgent questions or suggestions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/proxies/residential-proxies.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.