Proxy locations


North America

South America




See all locations

Network statusCareers

Back to blog

Residential Proxies Quick Start Guide

Maryia Stsiopkina

2023-09-293 min read

Oxylabs’ Residential Proxies comprise real IP addresses belonging to Internet Service Providers (ISPs). With these IP addresses,  you can bypass geo-restrictions 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.

Setting up Residential Proxies

To start with Residential Proxies, head to the Oxylabs dashboard and register an account.

Then, select a plan that fits your needs, or claim free trial proxies by contacting our Support Team. You'll be directed to the setup screen once you purchase Residential Proxies or sign up for a free trial.

Creating a proxy user 

When creating a proxy user, give it a name and a password.

Starting with Residential Proxies

Making a basic request

Once a proxy user is created, you’ll be given a cURL example that you can run in your terminal or any other setup you’re using.

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

curl '' -U 'customer-USERNAME:PASSWORD' -x '' 

Paste the given cURL in your terminal or other setup, replace USERNAME:PASSWORD with your credentials, click Enter, and then you’ll get your Residential IP address. See how to make a basic cURL request in the video below.

Location settings

Using a single backconnect entry node, you can set up targeting on the following levels via additional parameters in the username:

 Below is a sample credentials structure with the country and city parameters:

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

curl -x -U "customer-USERNAME-cc-GB-city-london:PASSWORD"

Session control

You can also use session control to keep the same proxy for multiple requests. You can do so by adding sessid-abc12345 to your username string.

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

curl -x -U "customer-USERNAME-sessid-randomString123:PASSWORD"

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

Note: You’ll need to replace USERNAME and PASSWORD in the cURL example with your proxy user credentials. Keep in mind that each request returns a new IP address as Oxylabs Residential Proxies rotate automatically.

For examples in other programming languages, visit our documentation

Response codes

See the most common response codes in the table below:

Response code Error message Description
400 Bad Request The request lacked a specified host for connection or encountered a general error while parsing an HTTP request.
407 Proxy Authentication Required The request is missing proxy authentication details, or the provided username or password is incorrect.
500 Internal Server Error The proxy server has encountered an internal error.
502 Bad Gateway The IP associated with your session ID is no longer accessible, or our available exit nodes do not match your specified criteria at the moment.
522 Timeout A proxy server didn't receive a timely response from the upstream server. Please attempt the request again.
525 No Exit Found The proxy was unable to locate an exit node that fulfills the request.

If you encounter any other response code, contact our 24/7 Customer Support for help.

Using Endpoint Generator

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

  • Output format -  choose the format for your endpoints (port, HTTP, HTTPS, or SOCKS5)

  • Authentication method - you can choose either username:password authentication or use whitelisted IPs

  • Endpoint type - you can choose between backconnect or country entry

  • Location settings - select a specific proxy location or leave Any to get a random proxy location

  • Session type - you can select either a sticky session to keep your IP address for up to 30 minutes or a rotating session to get a new IP address with each new request

Once you have the parameters set up - choose the number of endpoints and export it in your preferred format, such as  .csv, JSON, or .txt.

Overall, the Endpoint generator is a more convenient way to set up your endpoints and export them. You can learn more about the Endpoint generator in the video below.

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 Statistics section lets you see detailed information on how much traffic you use daily, daily breakdown, time range, and track the amount of requests. You can see usage graphs for any selected period and filter by users or export this data to a .csv file.

Additional resources

If you have any questions or want to give Oxylabs Residential Proxies a try with a free trial, contact our Support Team

Also, check out other developer-focused resources for more insights: 

People also ask

Are there any restricted targets?

Yes. To prevent abuse, some websites are restricted on our Residential Proxy network. The list includes but is not limited to:

  • All Apple domains, including iTunes and App Store

  • All Google domains, including Play Store

  • Entertainment (e.g., Netflix, Playstation)

  • Banking and other financial institutions

  • Government websites

  • Streaming

  • Ticketing

  • LinkedIn

  • Mailing

If you have questions about a specific target, please contact our Customer Support team for more information.

Is Public API available with Residential Proxies?

Yes, it is possible to incorporate your Residential Proxies into your existing infrastructure using our API, which follows the Open API protocol. For detailed information, please refer to the documentation for our Public API, accessible here.

Is whitelisting authentication available?

Yes, IP whitelisting is a feature that enables access to our Residential Proxy infrastructure through approved IP addresses. Within our dashboard, you can designate up to 10 IPs by default. You can easily add or remove these IPs using the Edit whitelist interface, where they are managed as a straightforward text list.

What is Oxylabs’ refund policy?

Only our Self-Service products are eligible for refunds, except for Pay-as-you-go plans. Additionally, we provide free trials for most of our products to both prevent refund requests and offer you the opportunity to test our proxies and scraping solutions. You can learn more by clicking here.

What is an Endpoint generator, and when should I use it?

An Endpoint generator is a tool that helps you effortlessly retrieve a list of endpoints by choosing the parameters you need, including region, output format, authentication method, endpoint, location, and session type. You should use the Endpoint generator to make the process faster and more efficient instead of inputting specific proxy parameters manually.

What are the technical requirements to start using Residential Proxies?

You can see the minimum technical requirements in the list below:

  • Servers to make requests from

  • A programmer proficient in a supported language

  • A web scraper and target URLs

  • A parser to extract the data you need

  • A database or storage solution

How do you create a fingerprint for successful scraping jobs?

A common mistake is using peculiar fingerprinting indicators and patterns that will give the scraper away. Thus, the best tactic is to decrease your browser's uniqueness when using proxies daily:

  • Initiate multiple concurrent sessions to mimic organic traffic and, thus, avoid getting blocked. For this, you can use either rotating or sticky sessions depending on your scraping case;

  • Another useful technique is to optimize HTTP headers. HTTP headers contain important information about the request. Resembling organic user behavior by optimizing headers can significantly increase one’s chance for successful scraping. 

  • Managing HTTP cookies is one more way to mimic human-like behavior. 

You can learn more about browser fingerprinting in this video.

Can I get a free trial for Residential Proxies?

Yes, to test our Residential Proxies, we offer a trial. You need to fill in a contact form on our website by clicking "Book a demo" or email us at Please note that the free trial offer is only available once per user.

About the author

Maryia Stsiopkina

Senior Content Manager

Maryia Stsiopkina is a Senior Content Manager at Oxylabs. As her passion for writing was developing, she was writing either creepy detective stories or fairy tales at different points in time. Eventually, she found herself in the tech wonderland with numerous hidden corners to explore. At leisure, she does birdwatching with binoculars (some people mistake it for stalking), makes flower jewelry, and eats pickles.

All information on Oxylabs Blog is provided on an "as is" basis and for informational purposes only. We make no representation and disclaim all liability with respect to your use of any information contained on Oxylabs Blog or any third-party websites that may be linked therein. Before engaging in scraping activities of any kind you should consult your legal advisors and carefully read the particular website's terms of service or receive a scraping license.

Related articles

Get the latest news from data gathering world

I’m interested