Residential Proxies Quick Start Guide

Oxylabs Residential Proxies are all about ethically sourced IPs associated with real internet users and real households. With these IP addresses, you can access region-exclusive content and collect public data without disruptions.

In this guide, you’ll find all the essential information needed for a smooth start with Oxylabs Residential Proxies. You can also teach your coding assistant or AI agent all about Residential Proxies in just a few steps with Agent Skills. Learn how.

Setting up Residential Proxies

1. Register and create an instance

To start with Residential Proxies, head to the Oxylabs Dashboard and create an account.

There, click + Add product instance and select Residential Proxies. Then set an instance name, choose an authentication method, and create the product instance.

Here's the same query in the code format for you to copy:

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

Paste the given cURL in your terminal or other setup, replace USERNAME and PASSWORD with your credentials, execute the request, and then you’ll get your Residential IP address.

Here's the same query in the code format for your convenience:

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

Here's the same query in the code format for your convenience:

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

The default session time is 10 minutes. However, you can prolong it up to 24 hours with the help of the sesstime parameter. See the list of all the supported parameters and how to use them in our documentation here.

If you need the same IP for the whole session, you can also use the sessid_oneip parameter. This session type keeps the original IP for as long as the proxy is available, up to the configured session duration. Unlike standard sessid sessions, no new IP will be assigned if the original proxy IP becomes unavailable. Instead, the request will return a 502 error.

For more details or examples in other programming languages, visit our documentation. 

Proxy protocols

Oxylabs Residential Proxies support four primary connection protocols depending on your scraping requirements:

• HTTP (http://) and encrypted HTTPS (https://) for traditional web automation

• SOCKS5 (socks5h://) for broad TCP/UDP traffic

• HTTP/3 (via MASQUE) for native QUIC connections.

While standard HTTP/HTTPS and SOCKS5 endpoints cover the majority of traditional scraping tasks, HTTP/3 provides native compatibility for more reliable connections with sites running modern web infrastructure. To explore full technical specifications, port details, and setup requirements for each protocol, visit our Protocols Documentation.

Advanced filters

Advanced filters allow you to narrow down the Residential Proxy pool based on the Internet Protocol (IP) version or platform (operating system) by using additional parameters in the proxy username string.

Note: Enabling advanced filtering may require a short KYC verification process.

IP version

IP version filtering allows you to filter proxies by Internet Protocol (IP) version. By default, Residential Proxies include both IPv4 and IPv6 addresses, but now the proxy pool can be filtered to receive only IPv4 or only IPv6 proxies.

What to do:

1. Decide which IP version is supported by your target website.

2. Add the ipversion parameter to your proxy username string.

3. Use ipversion-4 to receive IPv4 proxies or ipversion-6 to receive IPv6 proxies.

Below is the same example of a request using the IP version parameter but in code:

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

Note: Residential Proxies are dynamic, so availability cannot be guaranteed when combining IP version filtering with specific locations (for example, city or ZIP code).

Platform (OS)

Platform filtering lets you select the operating system of the residential proxy for the Transmission Control Protocol (TCP) connection. This makes it easier for the proxy’s device environment to match your client setup.

What to do:

1. Identify the operating system your request is intended to match.

2. Add the platform parameter to your proxy username string.

3. Select one of the available values: windows, macos, linux, android, or ios.

Here’s how a request with the platform parameter looks in code:

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

Note: Advanced filters can also be used alongside location targeting and session control covered above. For more details on advanced filtering, see our documentation.

Response codes

See the most common response codes in the table below:

Requests with errors originating from our infrastructure will additionally include an X-Error-Description response header, which will contain details about the error and what you should do next to resolve it. If you encounter any other response code, contact our 24/7 Customer Support for help.

Using Endpoint Generator

The Endpoint Generator is an automated tool in Oxylabs Dashboard that’s designed to generate custom lists of Residential Proxy endpoints. Endpoint Generator can be found in your Residential Proxy product instance Overview.

We suggest using our Endpoint Generator to easily retrieve a list of endpoints by selecting the necessary parameters. With this tool, you can retrieve a list of endpoints that include:

• Region – a region based on your location.

• Proxy protocol – choose from available proxy protocols: HTTP, HTTPS, or SOCKS5.

• Endpoint type – you can choose between backconnect or country entry.

• Location settings – select a specific proxy country or city location. Alternatively, leave Any to get a random proxy location.

• Session type – you can choose from a sticky session to keep your IP address, a rotating session to get a new IP address with each new request, or a one-IP sticky session that doesn’t switch IPs if the connection breaks before the session duration ends.

• Session duration – Choose the session duration on the slider for your sticky session between 1 minute and 24 hours.

Once you have the parameters set up, choose from popular options like cURL, Python, PHP, Node.js, GO, Java, or get integration details (host, port, username/password, and connection protocol)

Overall, the Endpoint generator is a more convenient way to set up your endpoints and export them. You can find more detailed information in our documentation.

Note: The purpose of the Endpoint generator is to create endpoints only. You need your own terminal or other setup to put the endpoints to use.

Usage statistics

The Usage section of your product instance lets you see detailed information on how much traffic you use in any time range, check daily breakdowns, and track the number of successful or failed requests. You can see usage graphs for any selected period and filter by targets or countries.