I signed up but I have not received an email confirmation from Luminati. What should I do?

Contact sales@luminati.io and we will get back to you as soon as possible.

I’m not being blocked by my target websites. Why should I still use Luminati?

Your block rate is not a reliable indicator of accessibility and accuracy of information. There are commercially available tools that help retailers and brands figure out that automated systems are attempting to access their site. In these cases, retailers will grant access but provide misleading information. With Luminati, you will receive the same data that a private user gets.

How does Luminati differ from TOR?

Compared with TOR, Luminati has a different model of service: While TOR has around 20K IPs, which are all marked and identified, Luminati's peer to peer (P2P) network has over 72 million residential IPs that are not identified as Proxies/Tor. Our architecture, which has an inbuilt IP rotation management layer, allows you to use our P2P network to send your HTTP / HTTPS requests via millions of IPs in every country and every city worldwide. With the right architecture on your side, you can achieve a failure rate of less than 1% (that is, you will almost never be blocked or cloaked).

Luminati residential peers

How do consumers join the Luminati network of peers?

Many applications (such as game applications), require their users to view a video advertisement at certain intervals, so that the game developer can generate revenues. This creates a particularly bad user experience, as it interferes with the experience of the application, wastes around 20MB of cellular data for the ad, and depletes the users’ battery.

Luminati offers an attractive alternative.

When these application vendors integrate the Luminati SDK, their users are offered the alternative to not watch these video ads in return for opting in to the Luminati network. Luminati only uses their device as a node on the network when it is not in use (so never interferes with the users’ experience), when the device is plugged in to power or charged, and always prefers WiFi over cellular data.

For every user that opts in to the Luminati network, Luminati pays a monthly fee to the application vendor, who passes that value on to the user by not displaying ads (or by not charging a premium for extra features in some cases).

That provides a much better user experience to the users, and thus the application vendor also enjoys a higher adoption rate of his/her product.

Users choose (opt in) to be a part of the Luminati network, and may opt out at any time. Luminati ensures that its application partners are fully compliant with this ‘opt in’ user flow.

View more on our SDK page.

How does Luminati protect the end users’ resources?

Luminati’s patented idle monitor technology ensures that an end user's device is used under strict limitations so that battery power, bandwidth and data plan are preserved. These limitations consist of a monitor that restricts the usage of the device if being used by the end user, a minimum battery level threshold, a preference for use only when charging, a maximum daily allowed bandwidth usage per device and weekly maximum usage.

What are the different IP Network?

Luminati has four types of IP networks: Data-Center, Static Residential, Residential, and Mobile.

  • Data center: offers a machine generated IP it is the most cost-effective and is commonly used for mass crawling of non-sophisticated target websites. Constructs of 700k unique IPs.Static residential Network: offers real residential IPs provided directly through ISP's. These IPs are most suitable for use cases that require permanent, non-rotating IPs, or for whoever needs a small amount of residential IPs. Constructs of 100k unique IPs.
  • Residential Network: provides a real, rotating, user IP, used for access to sophisticated target websites when you need to crawl, see and be seen as a real user. Constructs of 72+ million unique IPs.
  • Mobile Network: connects through a real, rotating, mobile connection of 3G/4G, used for targeting highly sophisticated websites and collecting mobile specific web data. constructs of 7+ million unique IPs
Create a Zone in the Luminati control panel, and define with IP type you want to use.

What are the different types of Data center IPs?

Shared IPs
Shared IPs are ips that can be used by one or more customers.
We have 2 pricing tiers for data center shared IPs:

  • Pay per usage - connects you to a pool of 20,000 IPs that consist of a fixed allocated range of IPs from every country available.
    These IPs can be continuously rotated within the pool of 20k as needed (specific countries can be chosen in chrome, the Proxy manager or through API)
    You will be charged only for the usage.
  • Pay per IP - purchase individual IPs for your use (with unlimited BW or cost per gb) in the country of your choosing. You will be charged per IP and usage.

Exclusive IPs
Purchase an IP that only you use to access a target site. The allocated IPs are dedicated for your use only.
This IP type is more lucrative and you can control the allocation of the IPs based on the following options:
  • Choose Target Domains as the target website you are accessing which provides dedicated IPs not used by any other customers on those domains.
    You can choose multiple specific domains you are working with or all domains.
  • Cooling period - a guaranteed amount of time the IP has not been used for the specified target site.

What are the different types of Residential IPs?

Shared IPs
Connecting you to our entire network of 72+ million IPs. You can rotate between different countries, cities and ASNs by using the Proxy Manager, Extension or the raw API.
The cost is per GB used, according to your monthly plan.

Exclusive IP
Gives you the option to have a group of residential IPs (see more about Exclusive residential IP) which ensure only you can use this Exclusive residential IP on a certain target domain.
Choose the number of Exclusive residential IPs to allocate (each Exclusive residential IP holds 3-30 residential IPs) in a certain country on specific domains.
The cost will be a calculation of amount of Exclusive residential IPs, usage and number of domains.

What are the different types of Static residential IPs?

Shared IPs
Shared IPs are ips that can be used by one or more customers.
Purchase individual IPs for your use in the country of your choosing. You will be charged per IP and usage.

Exclusive IPs
Purchase an IP that only you use to access a target site. The allocated IPs are dedicated for your use only.
This IP type is more lucrative and you can control the allocation of the IPs based on the following options:

  • Choose Target Domains as the target website you are accessing which provides dedicated IPs not used by any other customers on those domains.
    You can choose multiple specific domains you are working with or all domains.
  • Cooling period - a guaranteed amount of time the IP has not been used for the specified target site.

What are the different types of Mobile IPs?

Shared IPs
Connecting you to our entire network of 3+ million IPs. you can rotate between different countries, cities and ASNs by using the Proxy Manager, Extension or the raw API.
The cost is per GB used, according to your monthly plan.

Exclusive IPs
Give you the option to have a group of mobile IPs (see more about Exclusive residential IP) which ensure only you can use this Exclusive residential IP per a certain target domain.
Choose the number of Exclusive residential IPs to allocate (each Exclusive residential IP holds 3-30 residential IPs) in a certain country on specific domains.
The cost will be a calculation of amount of Exclusive residential IPs, bandwidth usage and number of domains.

What's the difference between Data-Center Vs Residential proxies?

  • Data-Center
    A data-center is an organization that offers large amounts of IPs with consecutive numbers, that are stored on the data-center's servers.
    • Pros: Data center IPs are more affordable than residential IPs. They are also called “static IPs” because they are always available and can hold a long session without the risk of becoming unavailable before the goal is achieved.
    • Cons: There are thousands of data centers worldwide. They are listed and their IPs can be identified as not real users, which makes them more easy to recognize and block. Some websites would display misleading information when they spot a connection attempt from a data center IP.

    Learn more about data center IPs.

  • Residential IPs
    The IPs of real end users’ devices.
    • Pros: When used correctly, residential IPs are nearly impossible to identify as proxy, as they are the real IPs of end users. Using Luminati’s Residential network allows unlimited concurrent connections and huge flexibility since it consists of over 72 million IPs located in every country in the world.
    • Cons: A Residential IP can become unavailable and be replaced during a session, since it’s a device of a real person that may use it or turn it off - Luminati takes extra measures to ensure the satisfaction and comfort of its network peers.
    Learn more about residential IPs.
  • Bottom line
    Try using data center IPs first and the more expensive alternative of residential IPs as a fallback option, that way you can reduce the costs of your operation and still get great success rate. Use Luminati Proxy Manager’s rules to easily create automated fallback in the “Waterfall” method to get best results at lowest costs. Use Luminati’s Exclusive residential IPs to get the pluses of Residential IPs while avoiding the minuses.

Network size

You can find the pool size of our Datacenter, Residential and Mobile networks in the architecture page.
Choose the network and country you are interested in the Input box and view the results in the Output box.

What is an Exclusive residential IP

An Exclusive residential IP is a group of exclusive residential IPs.

Each Exclusive residential IP contains between 10-80 IPs.

All the IPs within a Exclusive residential IP are from the same country and city (depending on the network you are using).

Using Exclusive residential IPs ensures that nobody else uses the same IPs with the same target sites as you do.

In some cases, and for specific domains, the residential shared network is block and those domains can be acess by using Exclusive residential IP only, for more info contact your account manager.

Find out more about how to download a list of your Exclusive residential IPs

What is IP allocation?

IP allocation is the act of allocating IPs of some kind to one of your Zones.
For example when creating a new data-center Zone and choosing 100 as the number of IPs you want, you are actually asking to allocate 100 datacenter IPs to your new Zone.
IP allocation is applicable for Data-center IPs or Residential and Mobile Exclusive residential IPs.
Find out how to allocate IPs and how to download a list of your IP/Exclusive residential IP.

What is the waterfall?

The Luminati Waterfall is a method to make successful requests by automatically passing them from the data-center network to the residential network and then to the mobile network. It improves success rate while lowering costs. Read more about it on the Luminati Waterfall page.

Can I assess how many IPs are available in a specific country?

Yes, you can assess the number of IPs available per country through this interactive diagram.
First, select the country from the drop-down menu. The number of available IPs in that country appears below.

Is communication between relays encrypted?

Yes. For requests to the super proxy you can use either HTTP or HTTPS. The communication protocol is encrypted by using a proprietary algorithm.

How HTTPS requests are calculated?

Since HTTPS requests are encrypted, we don't see the data insidethe request. in order to measure number of requests more accurately, we count switches between sending data to receiving data while kipping protocol related switches.

What is Super Proxy?

Luminati's load balancing servers, that manage the traffic between you (our customer) and the data center / residential network / mobile device.

What is an ASN (Autonomous System Number)?

An AS (Autonomous System) is a group of IP networks operated by one or more network operator(s) that has an external routing policy. ASN is the unique global identifier (a number) that is associated with every AS.

Why is Luminati faster than other proxy solutions?

Luminati has an inbuilt smart IP rotation management layer. Each request you make goes to one of our super proxies -- load balancing servers -- that then provide you with the IP address that is most likely to be available at the requested location.
That way Luminati proxy allows you to send an unlimited number of concurrent sessions, and has an extremely high success rate too. To speed up Luminati, it is advisable to initiate as many concurrent sessions as required. With the right architecture, you can outperform any other solution.

What is the impact on speed due to additional hops?

While using the Luminati Proxy means an additional hop (ie. 3 hops) per request, it also means having the ability to run unlimited concurrent sessions with an exceptionally high success rate, which nullifies the effect of the additional hop.

What is the maximal rate (hits per minute) at which requests can be sent through the network?

  • Residential network - no limitations. We have customers who send more than 20 million requests per day.
  • Data center and Static residential networks - we have rate limit of 500 req/sec per IP.
    If you send in a higher rate to a specific Data center or Static residential IP your requests will be returned with an error message:CODE 429: TUN_ERR: Too many requests per IP
    In order to solve the issue lower the rate of your requests or buy more ips to distribute the load of your crawler across more IPs.

Getting started

How do I start using Luminati's residential network?

We work hard to keep our network and our customers safe and strive to prevent abuse on the Luminati network. Therefore, prior to using Luminati's residential IP network, a Luminati representative will ask you to go through a short User compliance evaluation process. The User compliance evaluation process may include a quick intro video call and some verification of your company or personal information. Request access to Luminati's residential network here.
Watch now - How to start using the Luminati Proxy Manager

How do I start using Luminati's data-center network?

To start using Luminati's data-center network, click here. Our data-center network is self-serve and does not require any preliminary process.

How do I start using Luminati's mobile network?

To start using Luminati's mobile network, contact sales@luminati.io. Learn more about mobile IPs here.

Residential free trial

In order to test the Residential network, before committing to a monthly price plan, we will allow a free trial so you can test and be sure that your business needs are being fully accomplished using our services.

Free trial options

    We offer 2 types of free trial for the residential network, based on your account status:
  • Company - If you are signing on behalf of a company, you are eligible for a completely free 7 days trial upon verification of company registration and ownership
  • Non-Company - If you are signing as a freelancer or as an independent owner you will be eligible for a 3 days money back guarantee. In case you decide that the service is not suitable for your needs, you will be granted 3 days to claim back your used balance.


  • all trials are subject to a successful on-boarding process
  • The free trial is offered for those who sign for a monthly plan of $500 or more of the 'rotating' residential network (not static residential)

How can I set up a free trial account to test the Luminati residential IP network?

  • You will first need to Signup and activate your Luminati account.
  • After you verified your email address and have access to your account, fill the residential on-boarding form and your account manager will contact you to continue the process.
    it usually takes few hours to approve your Residential IPs access.
  • If you are not looking to use residential proxies and need Data center proxies you do not need to fill up the onboarding form.
    You can simply add funds to your account in the billing page and create Data center Zone.

My trial ended. what's next?

After your trial has ended, the system will disable your residential Zones to prevent any unwanted charges in your account.
You should take the following steps in order to continue using the Residential proxies:

  • Make sure you have a valid Payment method
  • Add funds to your account. You need to ensure you have enough balance to top up your monthly plan.
  • Enable back your residential Zones

Will I be billed automatically once my trial ends?

No you will not.
Regardless of having payment method set in your account or not, once the residential trial is over your account will be assigned with a 'Starter' residential plan of $500 (see pricing plans). This new pricing plan will be disabled and will not take effect unless you manually decide to enable it by activating your residential Zones.
You will not be charged by the system automatically.

What's a Zone?

A “Zone” is Luminati’s name for the specific set of parameters you have chosen to use for a set of proxy requests. When you join the Luminati network, you will automatically be assigned our standard configurations. You are free to customize those configurations according to your needs at any time.
When customizing your features, Luminati requires you to setup a “Zone” in which you may save and reuse a set of specific configurations and permissions for a project. You can set up as many Zones as you wish and each Zone may have its own specific configurations that you can use or change at any time.
Examples for some of the Zone's settings to choose between:

  • Network (Data center / Static residential / Residential / Mobile)
  • Exclusivity (Shared IPs / Dedicated host / Exclusive IPs)
  • Residential permissions (Country / City / ASN / gIP)

Watch how to create a proxy Zone video

How to limit Zones by domain?

In order to make sure you are using your proxies only on the websites you need, you can limit each Zone to a specific domain.
Also, you can block specific domains you don't want to target from each Zone.
Limiting Zone to a specific domain:

  • Go to Zones page
  • Click on the Zone you want to limit
  • Under 'Settings' section click the edit icon next to "Target domains"
  • Select "Allow only domains from list"
  • Enter the domains you want to target
  • Save

Block Zone for specific domains:

  • Go to Zones page
  • Click on the Zone you want to block
  • Under 'Settings' section click the edit icon next to "Target domains"
  • Select "Block domains from list"
  • Enter the domains you want to block
  • Save

How Can I estimate the cost of my account before signing?

Check out Usage and Price calculator. It is built to help you estimate the costs based on traffic (KB) you are currently running and number of desired IPs.

Can I add new IPs to an existing data-center Zone?

Yes. When adding more DC IPs to your DC Zone, the new IPs will be added on top the old IPs.

Can I get a list of all the DC IPs in a specific Zone?

Yes. Click on your Data center zone name and then click on Download IPs list . This will output a text file containing all your IPs in the format of IP:PORT:USERNAME:PASSWORD see image below:

Where can I find my credentials (IP/port/username/password)?

Credentials for raw API

  • Username and password: Your username and password for raw API requests can be found in the Zones page. Click the name of the desired Zone, and then in the window that popped up click the "settings" tab. You will find your credentials here. Notice that your credentials might be different for each Zone.
  • The full credentials for raw API (IP:PORT:USERNAME:PASSWORD) will be incorporated in the request string like this:zproxy.lum-superproxy.io:22225:USERNAME:PASSWORD
  • You can use our request builder to help you with creating full API requests

Credentials for Luminati Proxy Manager

  • IP - an IPv4 address to access proxy through. If Proxy manager is installed locally the IP address for credentials will always be: Proxy manager is installed on a remote server/machine use the IP of that server/machine
  • Port - the port number you want to use from the Proxy manager ports you created (i.e. 24000).
  • When integrating Proxy manager to a software which requires inputting IP:PORT:USERNAME:PASSWORD - USERNAME and PASSWORD should be left null.

How can I activate my account?

Contact sales@luminati.io and we will activate your account.

How can I setup a production account?

Choose between our plans. After you have chosen a plan, send an email to sales@luminati.io with the plan you have chosen and we will get back to you as soon as possible.

How do I install Luminati Chrome extension?

Luminati Chrome extension is available in the Chrome web store.

Whitelist IPs

For security reasons the IP address of every machine that runs Luminati has to be added to the whitelist of every Zone you will use.

How can I whitelist IPs inside the Luminati control panel?

  1. Enter the 'Zones' page in your Luminati control panel: https://luminati.io/cp/zones
  2. Click the specific Zone's name, then in the window click the pencil icon next to the Whitelist IPs
  3. Type the IP you want to whitelist
  4. Click Add and Save. You are allowed to add IPs, ranges, subnets or netmasks

Can I configure the Whitelist to include ANY IP?

Click the Edit icon, click the Remove icon next to the whitelisted IP you want to remove and Save . Note that choosing Any IP will weaken the security measures used to protect your account.

How can I whitelist IPs using an API?

You can whitelist your IP using this API:
curl -k -X POST --data "email={USER_EMAIL}&password={USER_PASSWORD}&customer={CUSTOMER_NAME}&zone={ZONE}&ip={IP}" https://luminati.io/api/whitelist/add

Is it possible to get more granular usage statistics?

There are several options to get more granular data:

  • Download a CSV file by clicking the 'Advanced' button on the top right corner of the chart, then choose CSV
  • Change the time span in the chart:
  • Change type of data to show in graph:
    NOTE: https requests might not be 100% accurate since we don't see the data in it. see How we count https requests

How to Add users to the account?

  • Go to "My settings" page
  • Click on the "+" button (Top left corner)
  • Add the user's details in the modal
  • Click "Submit"

After you successfully added the user he will receive an email to set a password in order to login to the account.

How to Add users to the invoice mailing list?

  • Go to "My setting" page, under "Company details" section
  • Click on the "+" button (On the right)
  • Add the recipient email
  • Click "Save" to add the recipient
  • Click "Save" to confirm the email

Once you successfully added the users they will start receiving the monthly invoices.

What is the dashboard Timezone?

The dashboard Timezone is UTC.

Suspending / reactivating my account

When should you suspend your luminati account?

If you know that you will not be needing your account or you are in between projects, its a good idea to suspend the account.

Suspending the account will stop monthly charges 24h after all zones are suspended.

Please note that suspending the account will release all IPs assigned to your zones

How do I suspend my Luminati account?

To suspend your account temporarily or permanently, click "Settings" on the sidebar and then in the top right corner of the page click the "Suspend account" button.

Can I suspend/activate my account via API call?

To suspend and reactivate your account by using API calls use one of the following commands:
Suspend account
curl -X PUT "https://luminati.io/api/set_status?customer=CUSTOMER&status=suspend_manual" -u "username:password"Reactivate account
curl -X PUT "https://luminati.io/api/set_status?customer=CUSTOMER&status=active" -u "username:password"


What is IP leak and how to solve it?

IP leak means your real IP is being revealed by the target site even though you are using proxy to mask your request.
Various 3rd party programs cause your actual IP to be leaked when using Luminati through a browser:

  • WebRTC
  • Flash
  • Java
  • JavaScript
  • ActiveX

To ensure this does not happen, make sure to turn these off to be 100% anonymous.

How do I reset my account password?

You can reset your account password through the password recovery page.
Note that this link will also appear after an unsuccessful login attempt.

What information should I send to Luminati when I report an issue?

To report an issue, provide us with:

  • Code snippets
  • The platform you are using
  • Your programming language
  • Logs and HTTP dumps if available (we request that you remove your trade secrets, including URLs and any other internal information from your code, dumps, and any other information you provide to Luminati)

Email this information together with your issue to: support@luminati.io

How do I handle a 502 error message (Bad Gateway - super proxies are refusing connections)?

Our API can be configured to request a new IP when you encounter a 502 error message:

How do I handle a 407 error message (Proxy authentication required)?

Encountering a 407 error message means that the client must first authenticate itself with the proxy. Resolving this issue requires adding the requested IPs, which are now refused connection, to the whitelist. For details, see Configure Whitelist IPs. If the issue persists, contact support@luminati.io.

Getting blocked and not sure why?

In order to understand if the block is generated by the target website or by your code you should run the following command in the terminal/CMD/git bash etc.
curl --proxy zproxy.lum-superproxy.io:22225 --proxy-user USERNAME:PASSWORD -k "TARGET WEBSITE" -I -sThis is a response example:
HTTP/1.1 200 OK
x-luminati-ip: m8ecb0c5cbf47c8c742dd2cc3b482ce9d
x-luminati-timeline: init:0,auth:136,dns_resolve_skip:0, p2p_init:1,a2a_reuse:0,p2p_conn:1709
x-luminati-tun-timeline: init:0,dns:67

HTTP/2 200
server: nginx/1.15.9 (Ubuntu)
date: Sun, 12 Apr 2020 09:23:39 GMT
content-type: application/json; charset=utf-8
content-length: 203
cache-control: no-store

The first set of the response is the successful connect to our super proxy.
The second set of response is the headers from the target website, if they include the header that looks like this 'http/x 200' it means the requests worked and you should look in your code for the blocking reason or contact support for assistance.

NOTE: you need to have a cURL installed to run the test

I need help with solving a technical issue

In case you have an issue that you attempted and failed to resolve, and it has been made clear by a Luminati representative that the problem does not originate in Luminati, you may ask your account manager for a Developer Review.
A Developer Review is a process in which one of Luminati's developers investigates and resolves the issue at hand for you, the customer.
This service is provided in selected cases according to Luminati's consideration, and costs $1,000 USD.


  • Luminati is not obligating itself to provide a Developer Review, and may refuse to provide the service in some cases
  • In case it is found during the Developer Review that the issue at hand did originate in Luminati, you will not be charged for the service


How can I contact Luminati's support?

Availability and response time

The support team is available 24/7.

It usually takes us less than 10 minutes to answer a support request.

Who answers my support requests?

An organic team that's comprised of our actual developers who build Luminati's products, and business managers who master the ins and outs of our service.

Open a support ticket

Can't find an answer to your question in the FAQ?
Log in and open a support ticket and our team of experts will address your issue personally

Reporting vulnerability

We appreciate any contribution that help us keep our users safe. Vulnerability can be reported to security@luminati.io. We will provide a modest bounty for a qualified and unknown vulnerability report.
For critical and high-impact security vulnerabilities we will provide a higher bounty at our discretion.
You can see more deatails about our vulnerability report rewards on our Reward Program page

Data center and Static residential

What is IPv4 format

IPv4 is a format in which many IP addresses are written that is used to connect devices to the Internet. It consists of four numbers between 1 and 255, separated by periods. Proxy services with data-center IPs often give out lists of IP addresses in this format to their customers.

How to use IPv4 format with Luminati proxies?

Because Luminati’s IP addresses are constantly changing or rotating, there is no list of IPs in IPv4 format like there might be when using data-center IPs. To ensure that the IPs are in the correct form, make sure to change your proxy settings to the corresponding port number of the IP address you want. Your device’s IP address will now be in IPv4 format.

Recovering IPs that were released from a zone

After reactivating your account or zone, you can use the IPs recovery feature to recover any of the IPs previously allocated to your zone which are still available in our pool.

Data center and Static residential 100% uptime

Luminati's Data center and Static residential involves hundreds of servers and hundreds of thousands of IP addresses and so small connectivity problems may rarely occur from time to time.

To avoid interferences we offer the 100% uptime feature, make sure to mark the checkbox in your zone:

Once activated, in cases an IP is having connectivity problems your request will be routed through a different IP in our pool from the same geolocation as the original IP address.

In case you ask for a specific IP in the request, we will not route it through a different IP.

Shared IPs

In the case of zones with shared IPs, the allocation of fallback IPs will be made directly from our shared pool

Exclusive IPs

In the case of zones with exclusive IPs, the allocation allocation process of fallback IPs will search for the most similar IPs using the following logic:
Use live IPs from within the zone → use available exclusive IPs from our pool → use IPs from our shared pool

Session continuity

To protect session continuity, the 100% uptime feature will not intevene in an existing connection. This means if an IP is experiencing connectivity problems while being used in an existing connection, the fallback IP will only start working once the existing connection will receive a socket hangup and a new connection is established.

Are changes in the code required?

Using the 100% uptime feature does not require any changes in your code or how you make requests. Just activate the '100% uptime' checkbox in your Zone settings and keep working as usual.


The 100% uptime feature can be switched ON and OFF via API

Free of charge

The 100% uptime feature is free of charge.

Geolocation databases

Geolocation databases are used by internet websites to determine the location of IP address its users are coming from. Luminati monitors and maintains correct records in the 4 main geolocation databases being used today: Maxmind, ip2location, db-ip and Google.

There are many othe smaller geolocation databases, most of which are using oudated records or flawed testing methods. Therefore it is highly reomended to use the geolocation databases mentioned above when testing your IPs. Updated values for each IP in all 4 databases are presented in your allocated IPs list which can be found in each zone.

Luminati Proxy Manager

What is Luminati Proxy Manager?

An advanced open-source (See project on GitHub) proxy manager to help you speed up development time with built-in data gathering features.
The proxy manager is a forwarding HTTP/HTTPS proxy on your side, to accelerate / compress / rotate / distribute / manage / monitor / report / log / debug traffic to your proxies around the world.
With Luminati Proxy Manager you can drive all Luminati's different networks.

Why should I use the Luminati proxy manager?

Proxy manager does common tasks of scraping, saving your engineers the need to write this code from scratch.
Save engineering cost on:

  • Auto-retry on fetched failures
  • Creating rules for automated rotation of IPs
  • Automatic blacklisting of IPs when getting bad results
  • Limiting the amount of requests sent per hour to achieve max scraping rate without getting blocked
  • Admin UI for monitoring and creating multiple proxies with different configurations
  • Enabling the routing of SOCKS5 requests
  • Optimizing speed by maintaining multiple concurrent connections
  • Listing IPs based on their performance for future reuse

Optimize proxy costs by:

  • Controlling which requests go to the proxy provider and which bypass the proxy to reduce costs
  • Routing requests to residential / data-center / mobile IP networks to get the most cost-effective blend

Debug code faster with:

  • Fine grained logging
  • SSL decryption, allowing to debugging SSL requests
  • HAR viewer for all your requests
  • Complete request history
  • Success rate measurement, based on user-defined triggers

Using the Luminati proxy manager will reduce development costs and efforts from your side - If there is anything you find missing in our proxy manager we will gladly investigate and add as a feature

Watch Luminati Webinar: How to start using the Luminati Proxy Manager

Install Luminati Proxy Manager

What are the options to install the Proxy manager?

Luminati Proxy Manager is an open source project developed by Luminati.
To install the Proxy Manager on Windows, simply download the Installer file.
To install it on Linux/MacOS, and for more installation options, visit the Proxy manager website.

How to install the Docker Proxy Manager image?

  • Install Docker $ sudo apt-get install docker.io
  • Install Docker Luminati Proxy Manager image $ sudo docker pull luminati/luminati-proxy
  • Check that Luminati Proxy Manager version is correct $ sudo docker run luminati/luminati-proxy luminati --version
  • Run the Luminati Proxy Manager $ sudo docker run luminati/luminati-proxy luminati
  • Docker to uses the host network --net=host
    • In order to open a only the required ports for the Proxy Manager$ sudo docker run -v ~/luminati_proxy_manager:/lpm -p -p -p luminati/luminati-proxy luminati --www_whitelist_ips --config /lpm/config.json

How to install and use the Proxy Manager on a remote server?

  • Log in as 'root' to the remote server
  • Install Nodejs
    Once you have finished the installation, run node -v and npm -v to see the nodejs and npm versions that been installed.
    Install NPM if missing.
  • While on 'root' within the remote server, install the Proxy Manager (using these options) and run it.
  • Set up the server to accept remote connections (see instructions here)
  • Configure the ports you require on your remote Proxy Manager
  • Send requests to the configured ports from your local machine by using [remote_server_IP]:[port_number]
    curl example: curl --proxy "http://example.com"

If you use Docker to manage your server deployment you can use our Docker image.

How to set up the Proxy Manager as a system service?

  • Log in as 'root' to the remote server (running Ubuntu)
  • Create a service file in /etc/systemd/system/lpm.service:
    [Unit] Description=Luminati proxy manager Wants=network-online.target After=network-online.target [Service] Type=simple Restart=always RestartSec=1 Environment=NODE_ENV=production ExecStart=/usr/local/bin/luminati User=ubuntu StandardOutput=null StandardError=null [Install] WantedBy=multi-user.target
  • Reload service files: $ systemctl daemon-reload
  • Start Proxy manager service: $ systemctl start lpm
  • Check status: $ systemctl status lpm.service
  • You have completed setting up Proxy manager as a service. You can now control your new service: $ service lpm stop/start/restart

How to manage multiple configurations on multiple servers?

If you are using linux server you can take a configuration file that is already working on one machine and copy it to the rest of your servers using the following command:
$ scp [file_name].json root@[Remote_server]:/root/.luminati.json

How to automatically upgrade your Proxy manager version?

Make sure you are always using the latest version by installing an auto upgrader which checks for updates in the background: $luminati --start-upgrader

  • Currently avialable for Linux and MacOS
  • You can start the Proxy manager process independently by running: $luminati

How to config the Proxy manager on Alibaba servers?

If the Proxy manager is running on your server but you can’t access it from another device. You’re trying to open the Proxy manager GUI and see an error is: ERR_CONNECTION_TIMED_OUT.
This means that you have not completed the external connections’ configuration.

  • Go to your Alibaba Cloud Management Panel, select your server and then click ’Security Groups’ tab under ’Network and Security’.
  • If there are no groups, create a new one.
  • Now we have to add rules to the server's security group - under ’Actions’ (to the right) click ’Add Rules’.

On the page that opens, you will see all the rules related to IPv4 / IPv6 access.
Now we need to open several ports to connect external devices to Proxy manager.
Click the button to add a security group rule. In the open form, you need to choose:

  • Rule direction: Ingress
  • Action: allow
  • Protocol Type: Customized TCP
  • Port range: 22999
  • Priority: 1
  • Authorization type: IPv4 address segment access
  • Authorized object: (The IP of your device)

Click the OK button.
Now you can open your browser and go to: "[Server IP]:22999"

Can I get an Proxy manager server?

Our Proxy manager is easy to install and maintain on your local/cloud server, but you may prefer to have Luminati host it for you. By shifting to Luminati's hosting service you do not need to worry about installing or monitoring. Luminati's 24/7 team is here to intervene, if needed.
The cost is $200-$500 depending on the server size. If you are interested, please contact sales@luminati.io

Integrate the Proxy Manager to your phone

Android settings

1. The Android and the machine using the Proxy Manager need to share the same WiFi connection
2. The Proxy Manager port must whitelist the IP of the Android machine
3. Go to the WiFi network configuration -> advanced -> manual proxy:
- Proxy host: The IPV4 address of the machine with the Proxy Manager ($ipconfig / for mac: $ifconfig)
- Port: 24000 (or other port you create)

iPhone (iOS) proxy settings

  1. The iPhone and the machine using the Proxy Manager need to share the same WiFi connection
  2. Whitelist the iPhone IPv4 in the Proxy Manager under ‘General’
    To find IPv4 follow these instructions:
    • Go to wifi settings.
    • tap on the blue “i” icon next to your network’s name.
    • See your IP address.
  3. Open the Settings app and go to WiFi
  4. Tap the name of the WiFi network you’re connected to
  5. Scroll to the bottom and you will find a section for HTTP Proxy. This is set to 'off' by default. Set it 'Manual' for manually configuring the proxy settings
  6. In the server slot enter the IPv4 address of the server where the Proxy Manager is installed
  7. In the port slot enter 24000 (or other port you create)

How can I transition from the API to the Proxy Manager?

Transitioning from the API to the Proxy Manager is easy.

By default, the Proxy Manager supports a drop-in proxy on port 22225 which is configured to behave in exactly the same way as our super proxies do via this port.

The easiest way to transition from the API to the Proxy Manager is as follows:

  1. Download and install the Proxy Manager from our Github page
  2. Run the Proxy Manager on a machine your code can access
  3. In your code, change the url from where you currently send requests to luminati (zproxy.lum-superproxy.io) to the local machine where your Proxy Manager runs on (usually
  4. Send your requests the same way you did use the API to

A more advanced way to integrate the Proxy Manager in your code is by configuring new proxies with your desired configuration through the proxy manager UI ( and by sending HTTP requests to the specified port.

In this case, you do not need to send the additional user parameter. For example, if you set a new proxy on port 24001 with a long session IP preset, you would send HTTP requests to without additional parameters, unless you want to send custom headers with the request.

Note: you can choose to disable the drop-in port (22225) by specifying the command line argument --no-dropin.

Can I use the Proxy Manager through API?

Yes. The Proxy Manager has fully working API you can use in order to create ports, change configurations, presets, proxy status and more. you can find documentation of the API endpoints here: API documentation

How to process specific data from target site

It is possible to collect specific content from your target site using a rule which will return a response as a json object according to your set up. To create a 'Process data' rule, follow these steps:

  • Go to the "Rules" tab
  • For "Trigger" select "URL"
  • Type the target website (e.g example.com)
  • For "Action" select "Process data"
  • For "Processing rule" type the Json (e.g., {"key": "$('#ID').text()"})
To watch an example of the steps above - Click Here
The response will look like this:

Can I access Luminati Proxy Manager from multiple machines?

Yes. The Proxy manager can be installed on your machine and be accessible from outside to send requests and to make adjustments to the Proxy configurations.
Note that you will need to take the following security steps to make sure the Proxy Manager is allowed to be used only by trusted sources.
In addition, you might need to allow access on your server's firewall in order to accept connections from different ports that are configured on the Proxy Manager.
See below instructions how to allow ports on your machine:

  • Windows
  • Linux / MacOS
    • Check if firewall is enabled: sudo ufw status
    • If firewall is active, open any port you are planning to use (24000 in this example): sudo ufw allow 24000
    • On your router: follow router specific instructions to forward port 24000 to your local IP address
  • CentOS
    • Open any port you are planning to use (24000 in this example): sudo firewall-cmd --zone="public" --add-port=24000/tcp --permanent
    • Reload firewall settings: sudo firewall-cmd --reload

If you want to access Luminati Proxy Manager UI (the dashboard), port 22999 should be open as well.

Can I run multiple instances of Luminati Proxy Manager on the same machine?

Yes, here's how to do it in Windows CMD:

  • Make sure Proxy manager is not currently running
  • Run the 1st Proxy manager instance:
    • Open CMD
    • Copy this snippet: luminati --no-dropin --port 24000 --customer [CUSTOMER_ID] --zone [ZONE_NAME] --password [ZONE_PWD] --no-config and paste it in CMD
    • Update the fields [CUSTOMER_ID] [ZONE_NAME] [ZONE_PWD] and run the snippet
    • The 1st Proxy manager instance is running, visit this address to use the Proxy manager UI:
  • Run the 2nd Proxy manager instance:
    • Open another CMD instance
    • Copy this snippet: luminati --no-dropin --port 24001 --customer [CUSTOMER_ID] --zone [ZONE_NAME] --password [ZONE_PWD] --no-config --dir ~/luminati_proxy_manager2 --www 2899 and paste it in the new CMD window
    • Update the fields [CUSTOMER_ID] [ZONE_NAME] [ZONE_PWD] and run the snippet
    • The 2nd Proxy manager instance is running, visit this address to use the Proxy manager UI:
Note that the ports of the first and second instances have to be different for this to work, that's why we used ports 24000 and 24001 here.

How to get IPs from specific locations?

To get IPs from a specific location, follow these steps:

  • Click on the port that you want to use location-specific IPs
  • Go to "Targeting" tab
  • Select the country you need from the country drop down list
  • Select the state you need from the state drop down list
  • Select the city you need from the city drop down list
NOTE: In order to select State and City you need to have the proper permissions in your Zone.

How to use IPs from many countries without creating many ports?

Use a port with the country set to “Any”. When sending the curl requests, set the desired country for each of your requests using a country parameter. If you want to send a request via an IP in Brazil, for example, your request will look like this:
curl -x lum-country-br@ http://lumtest.com/myip.json
The request's structure is:
curl -x lum-country-[country-iso-code]@ [IP]:[port][destination-URL]

The other option for controlling targeting dynamically and possibily different on each request is by using headers.
"x-lpm-country: [COUNTRY_CODE]"
Example request could look like this:
curl --proxy -H "x-lpm-country: us" http://lumtest.com/myip.json
You may also use headers for controlling state and city:

  • State: "x-lpm-state: [STATE_CODE]"
  • City: "x-lpm-city: [CITY_NAME]"

Running multiple browser profiles with different proxy settings

In the 'Overview' tab you can generate chromium browser for every port by clicking on the 'Chrome' icon next to the port number (see image below).
The browser will pop up on the screen and will be automatically configured according to the proxy settings of this port.
Open multiple browsers for each port to have unique and clean profile for each proxy port.
See image below as example:

How to control your IP session

The Proxy Manager has many ways for controlling sessions and manage the stability of the IPs used in the port.
Set up the rules which will define how the IP will rotate according to your business needs.

Can I hold residential IP for long period of time on a single session?

Yes. Choose Long session preset on the port 'Presets' drop down and it will automatically configure your port to tly ping the IP to keep it alive.
Note that Your use of a residential/mobile IP on the Luminati can be assured only as long as the peer's device is le, connected to internet and connected to power or has enough battery power.

How to control sessions consistency with session header

You can control your sessions using the Proxy manager by sending x-lpm-session header.

  • Add the header with any random session ID "x-lpm-session: random_session"
  • When using the same session the Proxy Manager will try to connect with the same exit node (peer/IP)
  • When you change the session value the Proxy manager will connect with a different exit node (new peer/IP)
  • To keep a given session alive you must send a request no more than every 60 seconds
  • Note that in order to use it with HTTPS requests you will need to enable SSL Analyzing and install the certificate
  • Here is an example: curl --proxy -H "x-lpm-session: rand123" http://lumtest.com/myip

    Can I automatically break the session before the residential IP is changed?

    Yes. you can choose 'Session termination' feature under 'IP control' in your Proxy manager admin panel to make sure the session will not continue if the current residential IP becomes unavailable.
    This feature will stop the session, ensuring your ip will not switch on the current session until you decide to take further action.

    How can I make all requests to be sent from specific Super Proxy server?

    Use a specific super proxy for your requests as follows:

  • Run this command in your command prompt/terminal: nslookup zproxy.lum-superproxy.io
  • In the response you will get a set of IPs of the 3 fastest super proxies available. Use this command several times to build a database of super proxy IPs
  • When running the Proxy Manager in your command prompt/terminal add the --proxy flag followed with the super proxy IP you want to use. Here is an example: luminati --proxy 111.222.333.444
  • All requests you make now will use the super proxy you chose
  • Note - using the same super proxy can cause low performance and latency issues - before using this function you should advise support team
  • Can I use the Luminati Proxy Manager with other proxy providers?

    Yes. Luminati Proxy Manager supports external proxies from other vendors. Connecting external proxies will allow you to optimize and manage all of your proxies in one place.

    Note that only HTTP connections are supported from external providers.

    How to setup external proxies?

    • Login to your proxy manager
    • Create new port
    • Select 'External' proxy
    • Add your proxies in ['username:password@IP:port'] format
    • Click 'Save' and you will have the external proxies available as one of the proxy manager's ports

    See example below:

    How to emulate real browser using curl request?

    Real browser emulation when sending requests through code is crucial for getting a successful response from the target site.
    In order to achieve that you should do the following steps:

    • Open Chrome browser
    • Open developer tools using Ctrl + Shift + I
    • Navigate to Network tab
    • Run your target URL in address bar
    • Right click the first request on the Network tab to open the context menu
    • Click 'Copy as cURL', and the full request with real browser headers will be copied to your clipboard
    • Use this request to emulate real browser

    How to measure successful requests?

    Requests that are returned with http status code 200, 300 or 404 are considered successful by default. In case you want to customize the rule to determine a successful request you can contact your success manager and he will configure that for you.
    The Proxy Manager calculates success rate as the number of successful requests out of the total requests and you can view your success ratio performance breakdown by "Port" and as "Overall" ratio.
    View your success rate (available from version 1.65.923) as shown in the example below.

    Custom headers

    Why should I use custom headers?

    Custom headers are mainly meant to make the request more specific. You should use it in cases when you need to mimic a human user behavior or pass custom parameters with your requests that are needed by the target site.
    Sending requests without headers can make it easier for the target site to mark the IP as proxy and can make your request get detectable by the target site and eventually reduce your request's success rate.

    How can I add headers to my Proxy manager ports?

    You can use the Random User-Agent in 'Headers' tab and/or add your own headers through the 'Headers' tab in your port settings.
    Once headers added on your port, all the requests made through this port will be sent with the added headers in the request payload.
    You can find specific User-Agents in this User-Agent database.

    See below example on how to set it up in Proxy manager:

    Refresh IPs

    Why to refresh IPs?

    Using the same IP for a long period of time makes it easier for the target website to mark the IP as proxy and can make your request get detectable by the target website. Refreshing your IPs will result in allocation of new IPs from Luminati instead of your existing ones in your pool allowing you to gain control over your pool and reach higher success rates.

    How can I refresh the IP using Proxy manager admin panel?


    Long single session (IP)

    All requests share the same long session (IP). For connecting a browser to Luminati, maintaining the same IP for as long as possible.

    Watch now: How to set a long single session


    Round-robin pool of pre-established sessions (IPs). For spreading requests across large number of IPs. Tweak pool_size, max_requests & proxy_count to optimize performance

    Watch now: How to set a round-robin preset

    Collecting only the information you need

    The Proxy Manager Online Shopping preset creates for you a port with all the necessary settings in order to collect only the relevant information you need and easily create product database info from the target site.
    The default settings with Online Shopping preset is for a product page that will return: title, price and product feature list.
    See example below:

    Watch now: How to set an online shopping preset

    The Online Shopping preset provide you with adjustable scraping modules. This means that you can set the response to fit your needs for each target site.
    You can find and set the modules in the "Rules" tab.
    Using the Online Shopping preset will ensure that you almost never be blocked on shopping sites.
    Example of request using product page URL including user-agent and cookie: curl --proxy "https://www.example.com/ASICS-Gel-Venture-Running-Black-Phantom/dp/B01N8PMBK9/ref=sr_1_3?s=fashion-mens-intl-ship&ie=UTF8&qid=1546755903&sr=1-3" -H "user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36" -H "cookie: session-id=146-8737485-9609151; session-id-time=2082787201l; ubid-main=130-06566-85313; x-wl-uid=1NA3QKNi3wfjNmXChAdgRGG7UKmcVow7hXYVwReXDvoLtZNKqen0THE0=; session-token=rffNUqxqqvEsRFrmPCK+u+SIlhyhH1YQrqRtRH8hNP6NX9Lflb+ISesFGyJ5Bd4jqCFXzXCT1x0Sfjhs/ldnme4C6goC+rErfaS11rrKdf/mYO3AEQaCkACSZqDUeriEo5UPcXrZtxi+hToVfcXIO4JwuCrH4qvONQAPrgE5J3CHPfyAMO/yAuh5MPyFEIL0MfGHYbhN3; skin=noskin; csm-hit=tb:3TVET6PFYJG42+s-X9THVXYX92M^|157698941^&t:15495102^&adb:adblk_no" --compressed -v -k


    • Collect the right header:
      In the browser console (i.e F12), go to Network tab and select the item named display.html and copy the Request header (e.g. POST) details such as user-agent and cookie.
    • Online shopping preset not working:
      Make sure you are targeting a product page (URL is containing /dp/) and Regex is true.
    • Using the same data-center IP or range multiple times with no change will flag the IP and the range

    How to use rules, triggers and actions?

    A rule is a pair of Trigger and Action. The Proxy Manager will scan the HTML response on every request and if the trigger rule you select is 'true' the action will be executed automatically. An example of a rule setup can be shown below:

    Watch now: How to set a Proxy Manager rules

    How to increase the speed of your requests using fast IP rule?

    If you need to maintain certain speed performance on your requests, this rule can help you achieve it.
    Setting up this rule will allow you to use IPs that are faster than others to increase the speed of your requests.

    In the example below you will see the following setup:

  • Rule type 'Maximum request time' with value of 1000 milliseconds
  • Action type 'Save IP to fast pool' and the 'Fast pool size' set to 10

  • What will happen with this rule?
    Once request time (the time to load your request start to finish) is up to 1000 milliseconds the IP (session) used for this request will be inserted into the pool. IPs will be added until pool size is reached (in our example once we have stacked 10 fast IPs).
    NOTE: Each IP in the pool will be pinged every 45 seconds in order to keep it connected (this operation consumes bandwidth).
    Once the pool size is filled with the desired amount of fast IPs, any future requests will be made using the IPs from the pool. Since those are proven to be fast, your request speed performance will improve.

    See image of the rule setup in the Proxy manager:

    How to get a list of banned IPs?

    Rules section can also be used to ban IPs which will trigger rules you set. This can be done in a similar to the Fast IPs pool.
    To get the list of IPs you choose to ban you can use the following API string:{port_number}

    How to unblock error codes

    Error code responds can trigger an IP refresh or try with new IP using the Proxy Manager Rules with the following steps:

    • Add a new rule at Luminati Proxy Manager, rules tab
    • Select 'Status code' as the rule type
    • Trigger the rule by selecting the relevant status code to scan (i.e 501, 402, 301, etc)
    • Select the desired outcome such as 'Refresh IP' or 'Try with new IP'

    Watch video: unblock error codes

    How to get notified by email when a rule is triggered

    The proxy manager offers an option to activate an email notification for each rule you create:

    When the rule will be triggered you will get an email notifying that a rule was triggered and will describe exactly what rule and in which port.

    Does Luminati Proxy Manager support multiple proxies?

    Yes. Luminati Proxy Manager supports multiple proxies.
    You can configure multiple proxies from Luminati Proxy Manager UI and from the command line.

    • From the Luminati Proxy Manager UI click the 'Add a proxy' button at the Proxies page and configure the new proxy
    • From the command line you need to provide a config file that will configure the different proxies with their different targeting settings.
      [ {"port":24000, "country":"us"}, {"port":24001, "country":"hk"} ]
      It is also possible to configure each proxy in its own JSON file, and pass Luminati proxy multiple config files in the command line

    How to multiply ports

    • Go to "General" tab
    • Choose the number of ports you want to multiply in the Multiply proxy port drop down

    Once you set the number of multiplied ports you need the proxy manager will generate the sequential ports identical to the port you configured.
    This is a very powerful feature when you need to create many ports with the same settings but only set it once.

    How to multiply ports per Exclusive residential IP

    • Go to "General" tab
    • Select "Yes" from the "Multiply proxy port per Exclusive residential IP" drop-down list
    • Select the Exclusive residential IPs from the Exclusive residential IPs list
    • Click "OK"

    Once you set the number of multiplied ports per Exclusive residential IP you need, the proxy manager will generate sequential ports with only one Exclusive residential IP per port from the list you choose.

    How to multiply ports per DC IP

    • Go to "General" tab
    • Select "Yes" from the "Multiply proxy port per IP" drop-down list
    • Select the IPs from the IPs list
    • Click "OK"

    Once you set the number of multiplied ports per IP you need, the proxy manager will generate sequential ports with only one IP per port from the list you choose.

    How to enable logging?

    Logging can be controlled from "Debugging" section.

    • Go to "Debugging" section
    • From "Log level" Choose the logging level you need

    The Proxy Manager has the following logging levels:

    1. none
    2. error (default)
    3. warn
    4. info
    5. debug
    6. silly

    Can the Proxy Manager save request/response history?

    Yes, by enabling the '--history' flag. When history mode is enabled, both request and response headers will be saved to a local database. They can er be accessed under the "Proxies" section. The history option can also track HTTPS, by enabling the '--ssl' flag. For additional details, see the Luminati Proxy Manager GitHub page.
    This can also be done through the Proxy Manager dashboard by abling Log request history and Enable SSL sniffing under the General settings section.

    How to improve success rate with the Log viewer

    The Log viewer presents real time HAR (HTTP Archive) log files generated from your requests that are sent through the Proxy manager.
    HAR (HTTP Archive) files contain a log of HTTP/S requests and responses, headers, body content and they are excellent for debugging HTTP/S requests.
    Using the Log viewer can help you debug your requests and easily improve your success rate by removing/fixing unwanted results.
    NOTE: In order to view logs of HTTPS requests you must enable 'ssl analyzing' and install Luminati ssl certificate. In addition, logs are running through port 22998 so you will need to allow this port on your local machine in case it is blocked.

    How to limit the amount of logs saved

    Saving logs is a great way to debug issues when they appear but for some request there is no need to save logs.
    Therefore, you can set a limit on the amount of requests you want to save logs for.

    • Click on the "General settings" icon →
    • Select "Yes" from the "Enable recent stats" drop-down list
    • Select from "Enable logs for" the number of requests/megabytes you want to save

    Trust Luminati SSL Certificates

    Some features require the proxy manager to have access to https traffic. This can be done by enabling the SSL analyzing feature on the Proxy manager port you are working with and adding the Luminati Certificate Autority (CA) as a trusted CA.

    How does it work?

    Behind the hood, Proxy manager will create a secure encypted https connection with the target site, decrypt the traffic to log requests and run rules based on your settings and then pass the response back to your client in an encrypted https connection with a certifcate signed by our CA certificate.

    How do I add the Luminati certificate as a trusted CA?

    Download the certificate and install it as described below in your preferred browser.
    If you use your own code, you will have to add our certificate as a trusted CA for self signed certificates. It is also possible to ignore SSL exceptions from your code for testing or if you use a HTTPS connection to our super proxy.

    Firefox browser

    • Type in the address bar: about:preferences#advanced
    • Go to Certificates tab and click View Certificates.
    • Go to Authorities tab and click Import.
    • Select the certificate file you have downloaded.
    • Make sure that "Trust this CA to identify websites" is checked and click OK.
    • Click OK and go to an SSL-protected website to check that everything is working as expected.

    Chrome browser

    • Download the certificate file
    • Go to the browser setting page and select Manage certificates
    • Click Import and Next
    • Click Browse and select the certificate you just downloaded, and click Next
    • Select Place all certificates in the following store and click Browse
    • Select Trusted Root Certification Authorities, click OK and then Next
    • Click Finish. "The import was successful message" should appear.

    Other browsers under Linux

    • Copy the downloaded certificate file ca.crt to the /usr/local/share/ca-certificates/ folder.
    • Run sudo update-ca-certificates. The output of the command should state that 1 certificate was added.
    • Go to an SSL-protected website to check that everything is working as cted.

    Other browsers under Mac OS

    • Double click the downloaded certificate file. You will see "Keychain Access" application.
    • Double click "luminati.io" certificate to see popup with certificate settings.
    • Select "Always Trust" in "When using this certificate" dropdown.
    • Close the popup enter your credentials when asked.
    • Restart your browser and go to an SSL-protected website to check that everything is working as expected.


    • Open up Safari
    • Navigate to this page and download the certificate using this link, but first read the following two items.
    • Click Install and provide your pass-code
    • Click Install in the top right corner and then Done
    • Go to iPhone "Settings"
    • Go to "About"
    • Go to "Certificate Trust Settings"
    • Enable the "Luminati.io" certificate
    • You can now go to an SSL-protected website in any browser installed in your system to check that everything is working as expected.


    • Download the following certificate and save it on your phone.
    • On your phone, look for the certificate through 'My files'.
    • Enter you password and press next.
    • Choose a name, preferably something you will recognize like Luminati.
    • Under 'Used for', choose 'VPN and apps' and click OK.
    • You can now go to an SSL-protected website in any browser installed in your system to check that everything is working as expected.

    How to run UI on HTTPS

    To run UI on HTTPS protocol you need SSL certificate and private key for your domain. Run Proxy manager along with environment variables SSL_CERT and SSL_KEY pointing to the according certificate files. Example:

    SSL_CERT=/path/to/ca.crt SSL_KEY=/path/to/ca.key luminati

    Once it is started you can access the UI using https://your-domain.com:22999/ link.

    What server do I need to run Proxy manager?

    You can run Proxy manager anywhere: on Linux, Windows, Mac or in a Docker instance. Because the amount of RAM, Bandwidth (BW) and disk space used varies based on your usage we recommend starting with a small simple server and scaling up horizontally or vertically to suit your needs.

    To start off we recommend using a server from Digital Ocean (because of their bandwidth policy) see specs below.

    Digital Ocean server specs:

    • 2GB RAM
    • 1 CPU
    • Ubuntu 16 LTS

    How to use parallel Proxy manager instances for high performance

    When you don't want to overload one Proxy manager with to many requests you can create several instances of the Proxy manager on different servers.
    The best way to do so is by following the next steps:

    • Install the Proxy manager locally and set all of the ports as needed
    • Save the config file
    • Install the Proxy manager on the servers you want to use
    • Import the config file to the luminati_proxy_manager directory in the servers
    • Split your traffic between the servers

    request 1 -> [first server IP]:24000
    request 2 -> [second server IP]:24000

    Using the Proxy manager with this method will make sure you are not overloading one Proxy manager instance and it will help you keep the same configuration across all instances.
    This means you can send requests from same port with the same country at the same time on each instance.

    Do I need to take any specific security measures when using Luminati Proxy Manager?

    It is important to ensure that Luminati Proxy Manager is only accessible when working either in environments that are strictly under your control or via a secured connection such as VPN. In addition, if installed on a remote server, it is best to:

    Block unwanted sources from using the Proxy Manager's ports

    Whitelist IPs on all your ports inside the Proxy Manager to ensure usage on those ports is only from allowed and wanted sources. While this feature is enabled, only the listed IPs will be allowed to send requests through the port with this configuration. Using this feature will ensure the bandwidth you pay for is consumed only by trusted sources.
    See example below how to add whitelist IPs for specific port:

    Block unwanted users from editing the Proxy Manager settings

    Whitelist admin access to ensure only authorized IPs can perform changes to your Proxy manager settings. This will block the admin page and the Proxy manager's API when it is accessed from outside the server (where the Proxy manager is hosted) from IPs which are not whitelisted.
    See example below how to easily add IPs to whitelist in General Settings:

    See example below, how to add whitelisted IPs to access the admin UI directly from the config file:

    Authentication using token

    If you are using multiple crawlers with changing ips to send requests to remote Proxy Manager server you will need to generate a token to use for authentication on the Proxy Manager:

    • Run Luminati process from inside the server
    • From the Proxy Manager's server run in terminal/command line:
      curl -X GET "" -H "accept: application/json"
    • You should be seeing the token response:
      "token":"TOKEN STRING"
    After generating a token you have two options: either use the token to whitelist the new IP once when the crawler server is set up or include the token in the proxy auth of each request:
    To make requests use the token in the proxy auth use username "token" and the actual token as the password, for example:
    • curl -x token:TOKEN_STRING@ http://lumtest.com/myip.json
    To whitelist your new server IP so you don't need to send it in proxy auth:
    • Copy the token from Proxy manager server to new crawler server
    • Make this request from your new server:
      curl [REMOTE_SERVER_IP]:22999/api/add_wip -X POST -H "Content-Type: application/json" -H "Authorization:[TOKEN_STRING]" -d '{"ip":"[CRAWLER_IP]"}'
    • Your crawler ip is now whitelisted on the Proxy Manager
    NOTE: this will not give access to the Proxy Manager's admin panel but only to send requests through the ports

    Local network

    If you want to access Proxy manager from a network where many people share the same IP then whitelisting IP is not strong enough for you. By whitelisting your IP you are giving an access to all the people from the same local network (corporate environments often look like that).
    Use local_login flag and Proxy manager will require authentication from each browser separately and a newly generated token will be stored in the cookies.
    luminati --local_login

    How to Integrating the Proxy manager with third party apps?

    The proxy manager is an Open-Source project that can be installed in various environments and used as proxy server in any application.
    Below are few examples for which Proxy manager can be used as the proxy server inside third party applications.
    Most of the third party apps require ip:port:username:password format. When you integrate the Proxy manager with any third party app there is no need in username and password and it is ok to leave username:password empty as each port in the Proxy Manager keeps the credentials of the used zone in it.
    Example for port 24000: IP:PORT:USERNAME:PASSWORD →[empty]:[empty]

    Check all the third party integrations

    How to integrate the Proxy manager with Multilogin (MLA)?

    How to integrate the Proxy manager with Insomniac browser?

    How to integrate the Proxy manager with Selenium?

    How to integrate the Proxy manager with Puppeteer?

    How to configure SOCKS5 protocol?

    In Proxy Manager, every port that is created will listen by default to HTTP/HTTPS and SOCKS5. In case a SOCKS5 connection is created, the Proxy manager convert will automatically convert the requests to HTTP/HTTPS. Meaning that nothing has to be configured in order to open SOCKS5 connection to the Proxy manager.
    See example of SOCKS5 request using curl on port 24000: curl -x socks5h://localhost:24000 http://lumtest.com/myip.json
    Same 24000 port can be used for HTTP like this: curl --proxy localhost:24000 http://lumtest.com/myip.json

    How to reduce the amount of data in a response?

    • Go to "General" tab
    • Select "Yes" from "Enable SSL logs"
    • Go to "Rules" tab
    • Select "URL" from "Rule type" drop-down list
    • Choose any file type to apply regex expression
    • Select "Null response" from "Action type" drop-down list

    In the following example below the Proxy Manager will return a null response (0kb and still status code 200) for all requests that ends with any of the file type endings .jpg|.png|.gif etc.
    Use this option when you want to reduce the amount of data you wish to get in your response.

    How to set a port name

    • Go to "General" tab
    • Set the port name in the "Internal name" input

    When managing many ports it is easy to lose track of each port's configuration. This is why It is important to create an internal name for each one.
    The name you choose for your port should be one that gives you info about the port configuration (e.g. 'US_verizon', 'US_mobile', etc).
    After you provided a name for your ports they will appear next to the port number in every feature of the Proxy manager. This way you will be able to manage all your ports easily, remember the settings of each port, assign users etc.

    How to add users to the Proxy manager?

    • Go to "Account Settings" tab
    • Click the "Add user" button on the Proxy manager users section
    • Add the user emails on the popup window
    • Click "Add users" to the add them

    How to reset the Proxy manager?


    Make sure the Proxy manager isn't currently running.
    On file explorer go to C:\Users\your_user.
    Delete the folder called luminati_proxy_manager.
    The next time you will run the Proxy manager all the logs and the config will be deleted.


    Make sure the Proxy manager isn't currently running.
    Run on terminal: rm -rf ~/luminati_proxy_manager
    The next time you will run the Proxy manager all the logs and the config will be deleted.

    How do I get support for Proxy Manager?

    You can either contact your Success Manager or submit a bug from the admin panel of the Proxy Manager (http://localhost:22999) see image below

    Luminati Chrome Extension

    What is Luminati Chrome Extension?

    It’s a Chrome extension that allows you to use Luminati from your browser with minimum setup.
    Watch video:

    Why should I use it?

    Use the Chrome extension to self-test your website, verify your ads, or simply browse a site as if from another country. It’s a powerful complement to the Luminati Proxy Manager and an easy-to-use tool for less technical users. You can also have people who don’t have access to the dashboard use the extension without knowing the account credentials.

    What features are available in the extension?

    Luminati Chrome Extension supports datacenter and residential IP browsing, allowing you to search from any country. You can adjust the user agent, customize configuration of the DNS to maximize discretion or speed, and set random IP rotation.

    How can I start using it?

    Once you have an active account on Luminati, install the extension here, set up your zone and start browsing from anywhere in the world.

    Can I let other people use the extension without providing my account credentials?

    Yes. They will need to go to the extension setup page and login with the customer name,zone name and zone key of the zone you wish to let them access. All the zone info is available in the Zones section.
    You can also use this link in order to automatically insert your guest-login credentials: https://luminati.io/cp/bext?customer=CUSTOMER-NAME&zone=ZONE-NAME&key=ZONE-KEY

    Can multiple machines use the extension on the same account?

    Yes. there is no limit on how many extensions are logging to the same account.

    How can I change the extension's settings?

    Open Extension setup page and change settings such as Zone, Country, Custom Headers, or anything necessary. Click 'Apply' when done, and your extension will be updated with the new setup.

    Why am I getting an 'error' message when I setup the extension?

    There are few possible reasons for proxy error when setting up the extension:

    • A zone was not selected. Make sure that the form is filled correctly.
    • Your account is 'disabled'. You can easily check this on your Dashboard.
    • You have a negative balance. Check this in your Billing section.
    • Luminati network status issues. You can check the network live status here.

    When should I use custom headers?

    Custom headers are mainly meant to make the request more specific. You should use it in cases when you need to pass custom parameters with your requests to the target site. Every header should contain Name & Value and you can add as many headers as you like.

    Does the extension work in incognito mode?

    Yes. Luminati extension works on both regular and incognito mode.

    To enable incognito support on Chrome, do the following:

    • Type chrome://extensions in the chrome address bar
    • Make sure Allow in incognito is checked

    Why login message keeps appearing

    Luminati uses cookies to remember your login credentials in order to keep your user experience at its best. If you are using third-party extensions that regularly removes cookies from your device then you'll see the login message quite often.
    How can you avoid getting login message?
    In the top right corner you can click on "Delete Cookies". This will delete all the cookies from your device except Luminati's and Google's cookies so you could keep using our service with no interruptions and keep your chrome extensions alive.

    Search Engine Results Pages (SERP)

    Which services are supported?

    Any “single query session” to SERP including:

    • Search
    • Shopping
    • Maps
    • Hotels
    • Images

    SERP benefits


    Get responses in JSON or HTML format for easy integration with any system

    Pay only for success

    You will only pay for successful requests

    Geo-specific requests

    Use UULE, country or city parameters and we will automatically send the data from the right peer

    Response Time

    Exceptional response times under 5 sec


    Get 100 results all on one page

    ASYNC requests (coming soon)

    send your requests with a unique ID, no delays and receive results in a batch

    Common Use Cases

    Organic Keyword Tracking

    Mapping a company’s ranking for various keywords in different locations

    Brand Protection

    Track top results for company brands and trademarks

    Price Comparison

    Search for products on online shopping websites and compare prices between different vendors

    Market Research

    Collect information about companies, contacts, locations and more

    Detect Copyright Infringements

    Search for images or other copyright‐protected content

    Ad Intelligence

    See which ads are showing for keywords in different countries including (double‐click & Google ad services)

    How it works?

    Technical Specifications

    • Session continuity is not supported as each request is sent from a different IP
    • Requests must be sent using HTTP (the Super Proxy will convert to HTTPS)
    • The service is only available via API (e.g. Chrome extension is not supported)

    Why use Luminati for SERP?

    Gather Accurate Data

    Our residential network provides the absolute truth by gathering SERP search data as a real-user.

    Reduce Costs

    Save money on data extraction engineers and IT professionals without worrying about server maintenance.


    Easily integrated into all 3rd party crawler software.

    Avoid Operational Headaches

    Each request is sent from a different IP ensuring no IP is flagged or banned.

    Built For Volume

    Luminati can support your growing traffic needs and peak periods.

    Real-Residential IPs

    72+ million real-user IPs in all geo-locations.

    How to start?

    Luminati’s API is compatible with multiple coding languages and is easy to integrate

    Search example (search for "pizza", over the "past month"):

    curl -v --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-CUSTOMER-zone-ZONE:PASSWORD 'http://www.google.com/search?q=pizza&tbs=qdr:m' -o results_page.html

    Photo search example (search for Reddit logo):

    curl -v --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-CUSTOMER-zone-ZONE:PASSWORD 'http:// www.google.com/searchbyimage?image_url=https://www.redditstatic.com/desktop2x/img/banner/banner-small-logo.png' -o results_page.html

    Shopping examples

    curl -v --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-CUSTOMER-zone-ZONE:PASSWORD 'http://www.google.com/search?q=lego+transformers&tbm=shop' -o results_page.html

    curl -v --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-CUSTOMER-zone-ZONE:PASSWORD 'http://www.google.at/shopping/product/232536990647203309?biw=2048&bih=1937&output=search&q=8053672401714&oq=8053672401714' -o product_page.html

    Maps example (HTML):

    curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-your_customer_name-zone-serp:your_password 'http:// www.google.com/maps/search/restaurants,+new+york/ @40.7436582,-74.0216375,13z' -o results_page.html

    Maps example (JSON):

    curl -v --compressed --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-your_customer_name-zone-serp:your_password 'http:// www.google.com/maps/search/restaurants,+new+york/ @40.7436582,-74.0216375,13z?lum_json=1' -o results_page.json

    Types of errors

    • 407: Auth Failed
      Various auth errors (wrong username/password, ip not whitelisted, Zone disabled, no permission to request specified city/ASN/region)
    • 502: No peers available
      Currently we have no peers in the region you requested
    • 502: only http requests are allowed, https is forbidden
    • 502: path must be one of /search, /complete/search, /searchbyimage, /shopping/product
    • 502: one of these parameters must be present: q, image_url
      Mandatory param is missing (q for /search or image_url for /searchbyimage)
    • 502: invalid value of gl param - should be country code
    • 502: requested language (hl param) is unsupported
    • 502: SERP is currently disabled
      We disabled SERP feature due to some reason
    • 502: text/shopping/image search is currently disabled
      We disabled specific SERP type due to some reason
    • 502: strict mode, query params not supported: gws_rd
      If you pass &lum_strict=1 as query parameter, we’ll check that all parameters will be passed to Search Engine without changes, otherwise we silently ignore unknown parameters
    • 502: strict mode, important headers not supported: user-agent
      If you pass &lum_strict=1 as query parameter, we’ll check that all headers will be passed to Search Engine without changes, otherwise we silently ignore unknown headers
    • 502: start/gbv param is not supported for mobile platform
    • 502: only start<100 and divisible by 10 is supported
    • 502: timeout
      Connection to peer timed out (after several retries with different peers)
    • 502: captcha_last_attempt
      Failed with captcha response (403/redirect to captcha) after several retries
    • 502: response_not_200
      Failed with erroneous response (4xx/5xx) from Search Engine after several retries


    How do I integrate Luminati as my proxy network?

    The recommended way to integrate Luminati is through the open source Luminati proxy manager. Alternatively, you can find the Luminati API here.
    For Firefox, chrome, or any other browser, use the Browsers API integration tool

    How do I integrate Luminati into a web browser automation tool?

    Integrating Luminati into a web browser automation tool such as Selenium or Puppeteer can be done by route to Luminati super proxy port which iszproxy.lum-superproxy.io:22225 and authenticate with your Luminati Zone credentials.
    The username and password of the specific Zone can be find in the API examples.
    Watch Luminati Browser Automation webinar
    Integrating Luminati super proxy with Selenium:

    const {Builder, By, Key, until} = require('selenium-webdriver'); const proxy = require('selenium-webdriver/proxy'); (async function example(){ let driver = await new Builder().forBrowser('firefox').setProxy(proxy.manual({ http: 'zproxy.lum-superproxy.io:22225', https: 'zproxy.lum-superproxy.io:22225' })).build() try { await driver.get('http://lumtest.com/myip.json'); driver.switchTo().alert().sendKeys('lum-customer-USERNAME'+Key.TAB+'PASSWORD'); driver.switchTo().alert().accept(); } finally { await driver.quit(); } })();

    NOTE: The latest FireFox version that supports the above code is 66.0.5. Newer versions support IP:PORT format, so using newer FireFox versions can be done through Proxy manager configuration.

    Integrating Luminati super proxy with Puppeteer:

    const puppeteer = require('puppeteer'); (async () => { const browser = await puppeteer.launch({ headless: false, args: ['--proxy-server=zproxy.lum-superproxy.io:22225'] }); const page = await browser.newPage(); await page.setUserAgent('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36'); await page.authenticate({ username: 'lum-customer-USERNAME', password: 'PASSWORD' }); await page.goto('http://lumtest.com/myip.json'); await page.screenshot({path: 'example.png'}); await browser.close(); })();

    Watch video: connecting Puppeteer with Luminati super proxy
    Note: Chromium user-agent include "HeadlessChrome" that need to be replaced as shown in the example above using setUserAgent.

    Which ports and protocols are supported by Luminati?

    Ports 80 and 443 are available by default, supporting HTTP and HTTPS protocols.
    The below table shows supported protocols by port:

    80 HTTP

    Luminati is able to support additional ports by request. Every request to support a new port will be followed by a dedicated and additional compliance process with the Luminati compliance team.
    For additional port permissions, contact Luminati Support.
    Examples of ports that require Luminati compliance review prior activation:


    Can I use Luminati on more than one device?

    Yes. You are not limited by the number of devices, IPs, sessions, concurrent connections, or Geo-Locations. We charge based only on the traffic going through our network. See the basic package for more information.

    How many concurrent sessions can I use?

    We do not place a limit on the number of concurrent sessions used.

    How do I configure IP rotation when using Luminati?

    When using the commands listed in the Luminati proxy manager GitHub page, the "requests per session" parameter is defined by using:--max_requests Requests per session [default: 50].Our API allows you to manage the rotation on your end by using the session parameters. This can be done by adding the session to the proxy username:
    lum-customer-Customer-zone-YourZone-session-rand39484Changing the session number changes the IP as well.
    IP rotation can also be managed through the Proxy Manager dashboard editing under IP Policy.

    Can I select the ISP or ASN of the IP?

    Yes. You can select an IP per ASN. Contact us at sales@luminati.io to add this premium feature to your Luminati account.

    How can I select an IP for a specific country?

    The country codes have standard ISO coding.
    You can find the right code for a specific country by using our interactive diagram and selecting a country from the drop-down menu.

    Can I select an IP per city?

    Yes. We offer a premium feature that allows selecting the location of the IP at a city level. To enable a city Zone in your account, contact your sales representative at sales@luminati.io.
    For instructions regarding the selection of a city using API, see How to use the Luminati API.

    How can I disconnect a browser session?

    You can use either of the following methods to disconnect a browser session:

    • HttpRequest:
      • Disconnecting session-1:new XMLHttpRequest().open('get', 'http://trigger.domain/hola_trigger?disconnect_sockets=1&all=1&reject=lum-customer-admin-zone-gen-session-1')
      • Disconnecting session-2:new XMLHttpRequest().open('get', 'http://trigger.domain/hola_trigger?disconnect_sockets=1&all=1&reject=lum-customer-admin-zone-gen-session-2')
    • Browser:http://trigger.domain/hola_trigger?disconnect_sockets=1&all=1&reject=lum-customer-admin-zone-gen-session-1

    Only change the proxy username as explained in out API.

    How do I keep the same IP over different requests?

    If you want to exit from the same IP over multiple requests, you should use the same session ID and make sure you exit from the same super proxy for the entire duration of your session.
    For example, get a specific super proxy IP:nslookup zproxy.lum-superproxy.ioChoose one of the resolved IPs and then use it with the same session:curl --proxy SUPERPROXY_IP:22225 --proxy-user lum-customer-CUSTOMER-zone-YOURZONE-session-rand1:YOURPASS "http://lumtest.com/myip.json"curl --proxy SUPERPROXY_IP:22225 --proxy-user lum-customer-CUSTOMER-zone-YOURZONE-session-rand1:YOURPASS "http://lumtest.com/myip.json"

    Which APIs does luminati support?

    Go to the API options page to see our wide range of APIs possibilities.

    Are the details included in the proxy authorization header visible to the target site?

    When the connection is established by using HTTP, the proxy authorization header is stripped from the request before the request is routed to the target site.
    When HTTPS is used, the removal of the proxy-authorization header depends on your framework.
    Under normal functioning this header is sent only in the CONNECT part of the request, in which case it will not get to the target site. This is the most common scenario, and therefore
    under normal circumstance and in most frameworks, there is no need to worry about the proxy authorization header being visible to the target site.

    However, if for some reason your framework sends this header as well in the GET/POST part of the HTTPS request, we have no access to the proxy-authorization header and cannot remove it.
    It is highly recommended to test this issue in advance by sending a request to https://lumtest.com/echo.json and examining the headers reported in the response.
    If the proxy-authorization header is exposed it will appear in the response.


    Can a peer intercept traffic?

    No. Luminati suggests to its customers to use HTTPS traffic, which is impossible to be intercepted. Customers that choose to use HTTP distribute their traffic over Luminati’s millions of peers, and thus no single peer (or even groups of thousands of peers) can piece together which Internet pages the Luminati customer is choosing to access

    Is there any way that the target website can trace the origin of the IP back to us?

    No. When a Luminati customer sends a request through the Luminati residential proxy network, that request is sent to a Luminati “Super proxy”, which is a server that strips away identifying information(if any), and sends that request to one of the millions of residential IPs that opted in to the Luminati network. The IP of the proxy on the Luminati network is a Residential IP, belonging to a regular Internet user in a geography and ISP of the Luminati customers’ choice. The request to the target website originates from that IP, and is not traceable further back to the Super proxy, or further back than that to the Luminati customer.

    GDPR Regulations

    Luminati is fully committed to complying with all relevant data protection legal requirements, including the new EU data protection regulatory framework - the General Data Protection Regulation ("GDPR").
    As an enthusiastic advocate of internet security and privacy, Luminati understands the importance of providing data subjects with greater control on their privacy and data. Therefore, we have taken considerable efforts to ensure that our privacy practices comply with data protection laws, including the GDPR, and the industry's best practices regarding, among other things, respecting data subjects' requests to exercise their rights. We are constantly examining applicable legal developments as well as the relevant provisions of the GDPR in order to develop tools for our customers' GDPR-compliant use of our services.

    How does Luminati handle our private data?

    Find out what types of info Luminati collects, how it's being used and other aspects of the way Luminati handles your data in the privacy policy page.

    Performance and best practices

    Can I request an IP change every 15 seconds?

    Yes. Our code snippet defines an IP change by number of requests (the default is 40), but can be modified by you so that your code would change every number of seconds as well.

    This can also be done through the Proxy Manager UI editing under IP Policy by setting Session duration (seconds) to the wanted value.

    Does Luminati compress the requests before sending them to the target site?

    No. The request will be sent as you specified it.
    Make a request to lumtest.com/echo.json - it will show you the headers it received.
    You will see it's not changed.
    curl -H "accept-encoding: deflate" --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-xxx-zone-gen:xxx "http://lumtest.com/echo.json"{"ip":"","country":"IN","geoip":2232796061,"geo":{"city":"","region":"","postal_code":"","latitude":20,"longitude":77},"method":"GET","httpVersion":"1.1","url":"/echo.json","headers":{"host":"lumtest.com","x-real-ip":"","x-forwarded-for":"","x-forwarded-proto":"https","x-forwarded-host":"lumtest.com","user-agent":"curl/7.46.0","accept":"*/*","accept-encoding":"deflate"}}HTTPS:
    curl -H "accept-encoding: deflate" --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-xxx-zone-gen:xxx "https://lumtest.com/echo.json"{"ip":"","country":"IL","geoip":674550570,"geo":{"city":"","region":"","postal_code":"","latitude":31.5,"longitude":34.75},"method":"GET","httpVersion":"1.1","url":"/echo.json","headers":{"host":"lumtest.com","x-real-ip":"","x-forwarded-for":"","x-forwarded-proto":"http","x-forwarded-host":"lumtest.com","accept":"*/*","user-agent":"curl/7.46.0","accept-encoding":"deflate"}}

    How can I see my current bandwidth usage with your API?

    You can see your current bandwidth usage with the following curl request:curl -H "X-Lum-Auth: lum-customer-CUSTOMER-zone-gen-key-PASSWORD" "https://luminati.io/api/bw"

    What happens if a target website blocks the IP?

    It should not happen with the correct usage of our system, but if it does, just open a new session with a different IP.

    Can you recommend ways for us to speed up proxies and drop slow ones?

    In the 200 Response there is a field called "x-hola-timeline-debug".
    The time in the field is the latency between the last IP and the site. You can use that to measure up to evaluate IPs.

    How do I exclude a specific IP?

    You cannot remove specific IPs because the super proxy allocates them randomly. However, you can make a simple query to get the specific IP you want to exclude. Go to http://lumtest.com/myip and disconnect (change session).

    Why did I get the same IP after changing the session ID?

    Sometimes an HTTP client caches the proxy username/password and as a result you may get the same IP even after changing a session. Ensure that your code accurately follows Luminati's 'high performance' sample according to the language you use. This sample contains a specific code, which ensures that the HTTP client library you use does not cache the proxy when switching sessions.

    Super proxy IP caching

    The server zproxy.lum-superproxy.io will get the most available 3 super proxy IPs. You can directly connect to each of those IPs by using your credentials.
    Caching the super proxy IPs might improve latency eliminating additional hop. It is recommended to cache the super proxy IPs every 6-7 days.

    Event log

    For a quick overview of your usage, go to the event log in your Zones page:

    The event log will show you one line of data for the first request made with each unique IP in the past hour.

    The presented data is:

    • Date: Time and date of the request
    • Zone: What Zone was used for the request
    • Source IP: What IP the request was made from
    • URL: The target site of the request
    • Result: Success or Fail of the request

    Billing and payments

    Payment verification

    Luminati maintains high compliance standards based on the principles of deterrence, prevention, and enforcement of malicious activities to ensure that our network is both safe for customers and ethical.
    It is for this reason that we are requesting that you identify yourself using your preferred payment method. We will charge you $1 and reward you with an additional $5 bonus ($6 in total) for your help and cooperation.

    What is the time zone used for my billing cycle?

    All billing calculations are made according to our dashboard timezone which is UTC+0. How this can effect your billing? You have the option to enable and disable your Zones. The time of enabling/disabling will be in UTC time therefore the daily charges will be applied accordingly.

    How Luminati billing works

    A minimum monthly commitment - Each plan requires you to commit to paying a minimum amount at the beginning of every month while your account is in “active” status. This minimum commitment will set the limits for your basic usage: once your usage goes over your minimum commitment amount, you will need to add additional funds to keep using our service. Learn more at our pricing page.

    If I suspend my account will I keep the IPs allocated to me?

    No. If you choose to suspend your account, the IPs currently allocated to you will not be saved.

    Can I use Luminati without monthly commitment

    Yes! you can use Luminati data center, static residential, residential, and mobile networks without monthly commitment.
    Simply click the pencil next to the zone name and adjust the plan to 'Pay-As-You-Go' Please note, in case the ip type is pay per ip/exclusive type or gips, you will be charged for the ips allocated to the zone

    How can I disable Zones to control my account usage and balance

    You can easily disable any of your Zones if you want to stop using it for a while. Our billing system will not charge for days when your Zones are disabled but rather only charge for the relative time the Zones were active. you can activate them back at any given moment from your control panel.
    NOTE: If zone was enabled and disabled on the same day, the charge calculation for the day will be as if it was enabled.

    • Disabling all residential/mobile Zones will also stop the pre-commit charges. as long as you have at least one active residential or mobile Zone the pre-commit plan will be applied and charged for.
    • Disabling Data center Zones or residential Zones with dedicated IPs will release all IPs to the pool

    What is the cost for refreshing data-center IPs?

    Refreshing data-center IPs will have a different cost depending on the type of IP.

    • Refreshing dedicated data-center IPs: $0.5/refresh/IP
    • Refreshing dedicated domain data-center IPs: $0.04/refresh/IP
    • Refreshing shared data-center IPs: $0.02/refresh/IP

    How does the Luminati billing cycle work?

    Luminati’s billing cycle starts on the 1st of each month. This means that you will be billed for your monthly account commitment automaticlly at the 1st of every month as long as your account status is active.

    How does the Luminati billing cycle work if I am only using data-center IPs?

    When customers only use data-center IPs, we calculate their cost on a daily basis. We subtract this daily cost from the current balance in your account, showing the remaining balance available for use. Costs are calculated according to the IP types used (shared vs. dedicated), as well as bandwidth/GB used. We also calculate any additional costs for added features (like exclusive time or dedicated domain/host).
    You will be billed for the costs described above on the 1st of every month. The balance remaining in your account will reflect the amount available for future use.

    What happens if I join Luminati in the middle of the billing cycle (in the middle of the month)?

    If you join Luminati in the middle of the month, your first minimum account commitment payment will be charged on the day you join and usage will retroactively apply only to the days in which your account was active during the month.
    Example: You join the Luminati Residential Network on the June 25th, your price plan has a $500 minimum monthly commitment and you make your first payment of $500.
    What will happen on July 1st?

    • Our system will see your account was active for only 6 days during June which are 20% of the month, so the relative part of the minimum monthly commitment will be $100. Unless the cost of your usage was higher than that, $100 will be your cost for June.
    • We will send you an invoice and take $100 from your balance against June cost, leaving your balance with $400.
    • Since on the 1st of every month your balance needs to comply with your minimum monthly commitment, we will now charge your credit card for $100 in order to top it back to $500 to comply with your minimum monthly commitment for July.

    Do you have any advanced pricing plans that cover unlimited data volume?

    Yes, our data-center and static residential plans covers unlimited data volume.
    You check our pricing calculator for unlimited traffic per month plan

    What happens when my usage goes beyond my minimum account commitment?

    When you have used 85% of your account balance during a given month, you will receive an email requesting that you add funds to your account. If you do not add funds to your account, your account will continue to operate until you have used 100% of your account balance. Once you have reached usage amounting to 100% of your account balance, your account will be suspended unless additional funds are added. We recommend to turn on the "auto recharge" to keep your account active and working.

    What if my usage in a given month is less than my minimum account commitment? Will my funds roll over to the next month?

    If your account remains in “active” status for the entire month, your monthly commitment will not roll over to the next month, regardless of whether your usage charges fell below the minimum commitment.
    While in 'active' status, your usage and billing calculations start over fresh on the first day of each month according to your price plan and monthly commitment.

    Can I limit my daily usage?

    Yes. In the Zone page under the "Usage spent limit" column it is possible to limit your daily usage in 2 ways:

    • Bandwidth(bytes)
    • Money spent(Dollars)

    Once you reach your daily usage the Zone will automatically be suspended.

    Note the Zone limit is calculated every 15 minutes and will not take effect immediately so a Zone might go over it's limit by 15 minutes of usage.

    NOTE: When the load is high statistics calculation may have a delay. In order to manually update the usage-statistics in your Zone, open the Zone by clicking on its name, go to the Statistics table, and press the [recalc] button near the desired date. Wait until the red "Loading..." notification at the top of the screen will disappear, and refresh the page. The stats will then be up-to-date.

    What if my account is not in “active” status for the entire month?

    If you have remaining funds in your balance during a month in which you were inactive, you will not lose your balance, but will be charged to bring that balance up to the minimum monthly commitment on the 1st day of the next month.

    I need my account to remain active at all times. How can I prevent suspension of my account?

    To ensure that your account is never suspended, we highly recommend that you use our automatic recharging option. It can be activated in the “billing” section of your account and ensures uninterrupted service. Auto recharge starts to work when your available balance drops below 85% of the total account balance. The amount set is entirely up to you and can be of any denomination.

    Does the cost structure differ by country?

    No, all countries are charged the same rate per GB.

    Which forms of payment do you accept?

    We have an automated billing system that supports payments that were carried out through PayPal, Payoneer, Wire transfer or credit card.

    How do I register for payment through PayPal?

    Go to the billing page click on "Add Payment Method" button and select "PayPal" as your payment method. Now you can click the "Add Balance" button, and you will be redirected automatically to PayPal.

    How do I register for payment through credit card?

    Go to the billing page and click on "Add Payment Method" and select credit card as your payment method. Now you can click the "Add Balance" button and make a payment with your credit card.

    How is Bandwidth calculated?

    The bandwidth is calculated according to the sum of data transmitted to and from the target site: request headers+request data (POST)+response headers+response data.
    Note that traffic used during your trial will be listed on your dashboard but will not be counted towards your bill.

    Do I need to log in online to deposit the prepayment funds? What is the link and login details for this?

    Yes, we send a prepayment billing request to your email which can be completed from the billing page.

    Will I receive an invoice?

    Yes. On the 1st of the month, you will receive an invoice. The invoice will provide details of your previous month’s usage. It will breakdown how your usage related to your minimum account commitment (and if applicable, any additional funds that were added during the course of the month).

    I will not be using Luminati on a daily basis but on a per-project basis. Do I still need to pay the entire minimum monthly commitment?

    During time periods where you are not using our service, you can turn off your residential Zones. Billing for residential services will only apply for the relative part of the month when the service was active.

    How many Zones can I open in my Luminati account?

    You can open up to 50 Zones in your Luminati account, free of charge. Each extra Zone will cost $1/month


    Premium domains

    Our premium domains allows access to some of the email providers for verification purposes.
    The list of our premium domains contains the following:

    • mail.yahoo.com
    • mail.yahoo.co.jp
    • mail.aol.com
    • mail.aol.fr
    • mail.com
    • gmx.com
    • outlook.live.com
    • hotmail.live.com
    • outlook.com
    • mail.google.com

    Using our premium domains can be done through the Datacenter network and the price for premium domain is $100/GB.

    Sending proxy requests


    • Client: Your machine running the scraping code. It connects to the Super Proxy to request URLs you wish to scrape.
    • Super Proxy: Luminati Super Proxy that distributes your requests through the Luminati network to the Luminati Proxy Peers.
    • Proxy Peer: The final device that sends your URL request to the target website. This is the IP that the website sees, it is a device that is part of the huge Luminati P2P network. It is a regular home PC, mobile phone or tablet, typically behind DSL, Cable Modem, or WiFi.
    • DC (datacenter) Proxy Peer: The final device that sends your URL request to the target website. This is the IP that the website sees, it is an IP that is part of the huge Luminati datacenter network.

    Using the system

    • You send your requests to the Super Proxy, and the Super Proxy relays them through a Proxy Peer on our network.
    • You can specify to the Super Proxy which country/state/city the Proxy Peer should be in, when to force a switch to a different IP address within the country, where DNS is resolved and other parameters.
    • The control is done by -country-CODE suffixes after username.
      Example for Brazil: lum-customer-{your_customer_id}-zone-{your_zone}-country-br
    • Country/City/ASN names added to your username string has to be connected , without dashes or spaces.
      Example for city targeting (New York City): lum-customer-{your_customer_id}-zone-{your_zone}-country-us-city-newyork
      Example for state targeting (New York State): lum-customer-{your_customer_id}-zone-{your_zone}-country-us-state-ny
      Our location reference is based on MaxMind's geolocation database, so spelling must be coordinated with their list

    Obtaining addresses of Super Proxies

    • Super Proxies are available under zproxy.lum-superproxy.io. This DNS name resolves to the set of currently fastest Super Proxies.

    Session IP persistence

    • In many cases you may want to run several parallel sessions from the same Client, use different Proxy Peers per session, and be able to change them when needed.
      This can be done by adding the session to the proxy username and targeting a specific Super proxy: lum-customer-{your_customer_id}-zone-{your_zone}-session-rand39484
      Generate the random number on thread startup, and change it when you want to change the Proxy Peer assigned for the thread's connection.
    • Use the same super proxy by storing the IP used from a DNS request to zproxy.lum-superproxy.io: nslookup zproxy.lum-superproxy.io
      if you don't use the same super proxy you won't be able to keep the same proxy peer IP.
    • Session ID can be any random string/counter: requests with same session string will use the same Proxy Peer (as long as possible); requests with different session strings will be assigned different Proxy Peers.
    • To force an IP change, just modify the session ID
    • If an assigned Proxy Peer(exit node IP) becomes unavailable, the Super Proxy will return an error "502 - No peers available" for the first request and then on the second request the super proxy will assign a new peer even if you do not change the session ID.
    • The Session IP is kept persistent up to 1 minute of idle time. After a minute with no requests, the IP is released back to the pool.
      To keep this Session/IP for longer, send a tiny keep-alive request every 30 seconds, to prevent this session from becoming idle for over a minute.
      This request may be anything small, such as /favicon.ico or even a request that returns 404 (as long as the web server does not disconnect the socket due to this request).
    • If you have multiple Clients and would like to ignore your Clients source IP (which is used together with you session ID to create a session), then you want to use global session then add glob_ as a prefix to your session:
      Generate the random number on thread startup, and change it when you want to change the Proxy Peer assigned for the thread's connection.

    Knowing the IP of the Proxy Peer

    For data center and static residential network types:

    • For HTTP the IP is in the response header x-luminati-ip
      Example for Proxy Peer IP of
      GET /index.html HTTP/1.1
      User-Agent: curl/7.35.0
      Host: example.com
      Accept: */*

      HTTP/1.1 200 OK
      Content-Type: text/html
    • For HTTPS the IP is in the CONNECT response header x-luminati-ip Example for Proxy Peer IP of
      CONNECT example.com:80 HTTP/1.1
      Host: example.com:80
      Accept: */*

      HTTP/1.1 200 OK
      Content-Type: text/html

    For residential and mobile network:

    at the residential and mobile network, the ip is encoded

    • For HTTP the IP is in the response header x-luminati-ip
      Example for Proxy Peer encoded of 123qaz123wsx123edc123rfv123tgb123:
      GET /index.html HTTP/1.1
      User-Agent: curl/7.35.0
      Host: example.com
      Accept: */*

      HTTP/1.1 200 OK
      Content-Type: text/html
      x-luminati-ip: 123qaz123wsx123edc123rfv123tgb123
    • For HTTPS the IP is in the CONNECT response header x-luminati-ip Example for Proxy Peer IP of 123qaz123wsx123edc123rfv123tgb123:
      CONNECT example.com:80 HTTP/1.1
      Host: example.com:80
      Accept: */*

      HTTP/1.1 200 OK
      Content-Type: text/html
      x-luminati-ip: 123qaz123wsx123edc123rfv123tgb123

    Super Proxy status

    • To “ping” the Super Proxy status run: http://zproxy.lum-superproxy.io:22225/ping
      You will receive its version number, IP and country where it's located.
      You can now tell if the super proxy is online if it returns the JSON properly like this:

    Controlling where DNS resolution is performed

    • If you use lum-customer-{your_customer_id}-zone-{your_zone}-dns-local domain names will be resolved and cached by the Super Proxy.
    • If you wish to perform the DNS resolution at the Proxy Peer, use lum-customer-{your_customer_id}-zone-{your_zone}-dns-remote
      This is slower, but will give you the same IP as users in your chosen country receive.

    Controlling from where the request is performed

    • You can choose to perform the request from the super proxy directly instead of the IP of the peer. In that case the IP of the request will be the one of the Super proxy. You will need to add '-direct' to your request authorization string. lum-customer-{your_customer_id}-zone-{your_zone}-direct

    Country-specific proxy peer IP

    • Example for United States: lum-customer-{your_customer_id}-zone-{your_zone}-country-us

    State-specific proxy peer IP

    • Example for California: lum-customer-{your_customer_id}-zone-{your_zone}-country-us-state-ca

    City-specific proxy peer IP

    • You can choose to use a specific City from MaxMind's geolocation database make sure to use the spelling from their list.
    • Example for Los Angeles, United States: lum-customer-{your_customer_id}-zone-{your_zone}-country-us-city-losangeles

    ASN-specific proxy peer IP

    • You can choose to use a specific ASN from a list of ASNs.
    • Example for ASN 1234: lum-customer-{your_customer_id}-zone-{your_zone}-asn-1234

    Carrier-specific proxy peer IP

    • You can choose to use a specific carrier from this list: a1, aircel, airtel, att, celcom, chinamobile, claro, comcast, cox, digi, dt, docomo, dtac, etisalat, idea, kyivstar, meo, megafon, mtn, mtnza, mts, optus, orange, qwest, reliance_jio, robi, sprint, telefonica, telstra, tmobile, tigo, tim, verizon, vimpelcom, vodacomza, vodafone, vivo, zain, vivabo, telenormyanmar, kcelljsc, swisscom, singtel, asiacell, windit, cellc, ooredoo, drei, umobile, cableone, proximus, tele2, mobitel, o2, bouygues, free, sfr, digicel
    • Example for carrier Deutsche Telekom: lum-customer-{your_customer_id}-zone-{your_zone}-carrier-dt
    • Example for carrier Sprint: lum-customer-{your_customer_id}-zone-{your_zone}-carrier-sprint

    Exclusive residential IP-specific proxy peer IP

    • The list of available Exclusive residential IPs appear in Zone Settings, in the 'Show allocated Exclusive residential IPs' link.
      Example for Exclusive residential IP us_7922_fl_hollywood_0: lum-customer-{your_customer_id}-zone-{your_zone}-gip-us_7922_fl_hollywood_0

    Can I choose a speicifc residential peer IP?

    • You can request a specific residential IP (without using Exclusive residential IP) if it is online and available from your Zone by adding the -ip option to the proxy username.
      This is useful if you already have the IP you want to use from a previous session and it's critical to use the exact same IP. For most use-cases we recommend using Exclusive residential IPs to have better availability in the same go-location or session flag to keep an IP you get during a single session of use.
      Example: lum-customer-{your_customer_id}-zone-{your_zone}-ip-111.222.333.444

    Can I use specific DC Proxy Peer?

    • Yes, when working with the DC or static residential network, you can use a specific ip which allocated to your zone by adding the -ip- flag, Example for DC IP 111.222.333.444: lum-customer-{your_customer_id}-zone-{your_zone}-ip-111.222.333.444

    Can I target ip by country when using DC network?

    • Yes, as long as you have ips matching the required country under your zone, you can use the following example to target ips from specific country. Example for United States: lum-customer-{your_customer_id}-zone-{your_zone}-country-us
      DC 'Global shared' Zones currently support the following countries: AM, AR, AT, AU, AZ, BE, BO, BR, BY, CA, CH, CL, CN, CO, CZ, DE, DK, DO, EC, EE, ES, FI, FR, GB, GE, HK, ID, IE, IL, IN, IT, JM, JP, KG, KH, KR, KZ, LA, LK, LT, LU, LV, MD, MX, MY, NL, NO, NZ, PE, PH, RU, SE, SG, TH, TJ, TM, TR, TW, UA, US, UZ, VN Note - luminati using maxmind light as the data base for country targeting.

    Mobile proxy peer IP

    • Use mobile ip: lum-customer-{your_customer_id}-zone-{your_zone}-mobile-true or lum-customer-{your_customer_id}-zone-{your_zone}-mobile
    • Don't use mobile ip: lum-customer-{your_customer_id}-zone-{your_zone}-mobile-false

    OS proxy peer

    You can use the following Operating Systems

    • Windows: lum-customer-{your_customer_id}-zone-{your_zone}-os-windows
    • Mac: lum-customer-{your_customer_id}-zone-{your_zone}-os-osx
    • Android: lum-customer-{your_customer_id}-zone-{your_zone}-os-android

    Using luminati in standard windows 10 settings

    • Get your proxy address zproxy.lum-superproxy.io:22225 for direct access for Proxy manager
    • Open start menu (press WIN)
    • Type 'Internet Options'
    • Choose 'Connections' tab
    • Open 'LAN Settings'
    • Un-select 'Automatically detect settings'
    • Select 'Use proxy server for your LAN'
    • Select 'Bypass proxy server for local addresses'
    • Type port and address (zproxy.lum-superproxy.io or in appropriate fields
    • Click OK
    • Some applications will interfere with setting up the proxy settings - if that happens, look for a proxy/vpn related application and deactivate them.
    • If you are using Luminati directly (without proxy manager), you should also configure proxy credentials:
    • Open start menu (press WIN)
    • Type 'Manage Windows Credentials'
    • Click 'add generic credential'
    • Type address without port or protocol (zproxy.lum-superproxy.io)
    • Construct user-name as explained earlier and type it in. Also type in the password
    • Click OK
    • Not all applications will honor the credentials, some applications (like Chrome) will ask for credentials themselves

    Using luminati in Android settings

    • Open your device Settings app
    • Tap 'Wi-Fi'
    • Touch and hold the Wi-Fi network name
    • Tap 'Modify' network
    • Tap the down arrow next to 'Advanced options'
    • Tap the down arrow next to 'Proxy'
    • Select 'Manual' and enter proxy settings:
      • Proxy host name: zproxy.lum-superproxy.io
      • Proxy port: 22225
    • Check the 'Authenticate Server' option and enter username and password as can be found at http://luminati.io/cp/zones, click on the Zone name, then click on 'Settings' tab. If this option is not available, your browser will prompt you to input these values
    • Tap 'Save'

    Using luminati in iPhone settings

    • Open your device Settings app and go to Wi-Fi
    • Tap the name of the Wi-Fi network you are connected to
    • Scroll to the bottom and you will find a section for 'HTTP Proxy'. This is set to 'Off' by default. Set it to 'Manual'
      • In the server slot enter: zproxy.lum-superproxy.io
      • In the port slot enter: 22225
    • Toggle the Authentication to 'On'
    • Enter username and password as can be found at http://luminati.io/cp/zones, click on the Zone name, then click on 'Settings' tab.
    • Note: if you need to change the proxy credentials you may encounter a bug in iOS proxy settings. Proxy username and passwork are cached by host name and can't easily be changed. To over come this bug either use Proxy manager to control proxy credentials of use a different host every time you need to change credentials. You can use session-RANDOM_ID.zproxy.lum-superproxy.io to create a new host domain every time.

    Using HTTPS for connection to Super Proxy

    let auth = 'USER:PASS'; let https = require('https'); let agent = new https.Agent({keepAlive: true, keepAliveMsecs: 5000, servername: 'zproxy.lum-superproxy.io'}) let conn = https.request({ host: 'zproxy.lum-superproxy.io', port: 22225, method: 'CONNECT', path: 'lumtest.com:443', agent, headers: { 'Proxy-Authorization': 'Basic '+Buffer.from(auth).toString('base64'), } }) .on('connect', (res, socket, head)=>{ if (res.statusCode!=200) console.error('CONNECT failed:\n'+res.headers); res.on('error', e=>console.error('CONNECT error: '+e.message)); socket.on('error', e=>console.error('socket error: '+e.message)); socket.on('timeout', e=>console.error('socket timeout: '+e.message)); https.get('https://lumtest.com/myip.json', { socket, agent: false, }, res=>{ res.on('data', d=>console.log(Buffer.from(d).toString())); }); }) .on('error', console.error) .end();

    Using HTTP CONNECT for whois

    • To use this method of sending raw data through the proxy for WHOIS protocol you must get approved by your account manager
    • let auth = 'USER:PASS'; let http = require('http'); let conn = http.request({ host: 'zproxy.lum-superproxy.io', port: 22225, method: 'CONNECT', path: 'whois.eu:43', headers: { 'Proxy-Authorization': 'Basic '+Buffer.from(auth).toString('base64'), } }) .on('connect', (res, socket, head)=>{ if (res.statusCode!=200) console.error('CONNECT failed:\n'+res.headers); res.on('error', e=>console.error('CONNECT error: '+e.message)); socket.on('error', e=>console.error('socket error: '+e.message)); socket.on('timeout', e=>console.error('socket timeout: '+e.message)); socket.on('data', d=>console.log(Buffer.from(d).toString())); socket.write('test.eu\r\n', console.error); }) .on('error', console.error) .end();

    Accepted usage

    How does Luminati ensure the legitimate use of its proxy network?

    Only companies that pass Luminati’s strict User compliance evaluation process successfully may use the Luminati network.
    These include the top retailers, ad networks and travel agencies in the world.
    Prospects who wish to use Luminati’s Residential network fill a “Residential activation” form, in which they identify themselves by providing personal details (email, phone number, address, social profile, payment method and more) and sign an agreement in which they confirm that all their activity is legal.
    After their details are checked and verified manually, they may be approved.
    IN addition, Luminati’s systems and personnel continuously monitor the customer's activity to ensure that the usage is compliant with the agreement.

    Is crawling an acceptable use case?

    We allow you to use our service, provided you are using it for legal and legitimate uses and in compliance with our license agreement. It is up to you to make sure that the way you use the service complies with the laws applicable in your country.

    Is crawling a particular site legal?

    The use of a crawler to extract data from a website may be done legally in relevant business relations. Under certain circumstances and in some specific jurisdictions, crawling may be in conflict with applicable regulation or in violation of the particular terms of service of the crawled site. Therefore, prior to engaging in crawling activities of any sort, you should consult with a lawyer authorized to provide legal advice in your particular area, and carefully read the applicable terms of service.

    What is reselling and is it allowed with Luminati?

    Reselling means providing Luminati services or products as a paid solution to a third party which is not a Luminati customer.
    Luminati does not offer nor allow any form of reselling for any of its products or services. Any kind of such reselling will be perceived as a breach of Luminati terms of use.

    What is the accepted usage of unlimited bandwidth in our data center network?

    Luminati reserves the right to periodically review the usage levels of unlimited bandwidth datacenter IPs allocated to customers; this is to ensure that the level of traffic per IP is not being overused.
    In cases where excessive usage of unlimited bandwidth is detected, Luminati has the right to limit future bandwidth usage of the unlimited bandwidth or apply additional charges.

    A fair usage rate limit of 4000 connections per second per IP is enforced by our system. The fair usage rate limit may be updated periodically.

    In case your usage reaches the fair usage rate limit you will be informed via email so that you can adjust the amount of allocated IPs in your Zone to fit your traffic volume.

    Luminati SDK

    Luminati Referral Program

    API documentation

    API documentation

    Buying IPs to fit your needs

    Network types

    • When to buy residential IPs?

      Residential IPs are private IP addresses, meaning that your requests are routed through a real user when accessing the web. Buying residential IPs ensures that you will never get blocked or misled.

    • When to buy data center IPs?

      Data center IPs are also known as static IPs.

      A Static IP means you can keep using a specific IP for as long as you need (one long single session). These are more economical than Residential IPs.

    • When to buy mobile IPs?

      Mobile IPs are a segment of residential IPs that are connected to the Internet via cellular (3G / 4G) connection, rather than WiFi or cable. Mobile IPs are commonly used to verify that your ads are being displayed correctly on mobile devices with different providers.

    Exclusivity types

    • When to buy shared IPs

      Shared IPs are the easiest way to start using Luminati network. They refer to global pool of IPs in various countries that are shared amongst many users to access numerous sites. you can use this option as the first entry point and scale to more exclusive one when getting blocked or misled.

    • When to buy Exclusive IPs, with exclusive domains

      Exclusive Domains promise that you will be the only one using those IPs for the target sites that you have chosen.

    • When to buy Dedicated IPs, with unlimited domains

      Unlimited Domains refers to IPs that are completely dedicated to you. No one can use those IPs while you are using them. Buying dedicated IPs ensures that your results will not be affected by another user of proxy services.

    How to allocate IPs?

    Allocation of IPs is done through the Zones section of your account.
    To get started you need to create a new zone and among other settings, choose the number of IPs you want and save.
    You can also update number of allocated IPs by editing the number of IPs in your zone.

    When turning a zone off all IPs allocated to it are released, so when you turn the zone back on you will have new IPs allocated to it.

    How to download a list of my IPs?

    In order to download a list of all Exclusive residential IPs or datacenter IPs allocated to one of your Zones there are 2 possible actions:

    1. Download your IP list through your Luminati CP Zones section by entering the specific zone and clicking on 'Download Exclusive residential IPs list' (for Exclusive residential IPs) or 'Download IPs list' (for datacenter) under settings
    2. Download your Exclusive residential IP list via API using the following command:
      • For Exclusive residential IPs:
        curl "https://luminati.io/api/get_route_vips?" \ -H "X-Lum-Auth: lum-customer-ACCOUNT_ID-zone-ZONE-key-ZONE_PASSWORD"
      • For datacenter IPs:curl "https://luminati.io/api/get_route_ips?" \ -H "X-Lum-Auth: lum-customer-ACCOUNT_ID-zone-ZONE-key-ZONE_PASSWORD"

    Cost effectiveness of residential IPs

    How did we calculate this table?

    Your company needs to collect information from the web by sending 1,000 http requests per hour to a specific website. You write the scraper code and run it through a server. The target website allows 50 requests per minute from the same IP before blocking your scraper. Now, you have to purchase more proxies.

    Assuming you choose datacenter proxies:
    You don’t want to share IPs, so you buy 200 dedicated data-center IPs. You code the integration of the scraper with the new data-center proxies for 2 hours and then run the new program. This time, it takes 3 days for your target website to detect your scraper. Once your proxies are detected, you’ll have to purchase new proxies and repeat this process again, checking each day to make sure the proxies haven’t been detected. Cost per month (all numbers are from real customers):

    • 200 dedicated IPs: $500
    • Bandwidth: (1000 request X 20KB per request X 24 hours X 30 days = 14.5GB): $3 per month
    • Developer (2 hours integration X 10 + 1 hour every 3 days for managing the proxies): ~3 days of work a month or ~$900

    Your total cost per month will be at least $1400 for just these things alone, and the salary of $30 per hour for a developer is very conservative. Additionally, this doesn’t account for a lack of information reliability if your target website sends misinformation before blocking you or if your information flow is cut every few days, which can be detrimental to your brand or your revenue stream.

    Assuming you choose Luminati residential proxies:
    You buy a basic package of 40GB with access to unlimited residential IPs. It takes 2 hours to integrate your scraper. Due to an average of 3 million residential IPs available each day, your target website can’t detect your scraper, allowing you to focus on other projects.

    The bandwidth and unlimited IPs cost just $500 per month. Your information is always reliable because your requests are always successful and access is never cut in the middle of the month. When your business grows as a result of this scraping and your projects exceed 600MB each month, the difference in costs can be much higher than just ~$1000.

    Luminati also allows you to suspend your account when not in use, so your cost can be lower than $500 per month. Start by using the $5 voucher for free data-center traffic to test Luminati’s benefits and then ask for access to our residential network for cheap and reliable data collection.

    Become a Luminati professional

    How to crawl a website without getting blocked or misled (cloaked)?

    Why should I care?
    When a target website detects crawlers from a proxy (datacenter) IP, it typically

    • Blocks the IP, or
    • Presents the IP with purposely misleading information, or
    • Throttle down the response rate

    How does the target website identify my crawling activity?
    Target websites log the IPs of whomever visits them and analyzes the activity of these IPs. Assuming you are using a traditional data center proxy, the target website can:

    1. Identify that the activity from a single IP (the rate of requests) is much greater than what a human can accomplish in a given timeframe
    2. Identify that the IP address originated from a proxy server list, which these target websites have access to
    3. Identify that the IPs have the same subnet block range
    How to prevent being detected?
    1. To prevent being detected by the amount of requests per IP, you can reduce the number of requests per second. However, this will reduce your crawling speed
    2. To prevent the target from identifying your IP as coming from a proxy server, you must rotate your requests through residential IPs. You should be able to circulate through enough IPs that the target website can not detect your activity
    3. When using residential IPs there is no subnet block range
    By using a traditional proxy solution, it’s only a matter of time before the target website will identify your crawling activities, and can block or provide you with the wrong information.

    How to get an IP in a specific city

    Why should I care?
    Example: If you are responsible for testing Yelp’s city level service - you need to check the site from 10,000 different cities around the world.

    How to get an IP in a specific city?
    If you only use a traditional data center proxy solution for your information collecting tasks, you are limited to where these datacenters are located. Large residential networks can get you IPs in any specific city in the world.

    How to accelerate your web scraping

    Why should I care?
    If the number of requests you rotate through a single IP are higher than what target websites allow, the website you target will identify your IP and block or mislead you with false information. It means that your information collecting can be much slower than what you’re used to.

    How do I improve the speed of my data harvesting?
    Assuming you're running 10 million requests, 1 request per second per IP with 1000 data center IPs, your routine can take about 3 hours. With 10,000,000 residential IPs, your routine can potentially take 1 second.

    Guidelines to rotate multiple parallel sessions through Luminati’s residential network:

    1. Open Luminati Proxy Manager
    2. Go to the ‘proxies’ tab
    3. Check the port of your residential zone
    4. Edit in the port settings ‘preset’ to ‘round-robin (ip) pool’
    5. Route your requests to{portnum} where the {portnum} is the port of the residential zone

    How to rotate your IP address

    Why should I care?
    When many requests are sent to a website from the same IP, the website can tag the IP used as a crawler and send misleading information or block you. Periodically changing, or rotating, your IP address helps prevent a target site from identifying your IP as a crawler. Rotating your IPs can drop your failure rate to below 1%.

    How do I rotate my IP address?
    With its easy-to-use proxy manager, Luminati allows you to control:

    • Number of requests permitted before changing the IP
    • Amount of time between IP changes
    • Quantity of IPs in your rotation pool

    Guidelines for rotating your IP address with Luminati:
    1. Open Luminati Proxy Manager
    2. Go to the ‘proxies’ tab
    3. Click on the proxy you want to edit, then on the edit button
    4. Browse rotation options under 'Preset' or 'IP Policy'
    5. Route your requests to{portnum} where the {portnum} is the port of the residential zone

    How to use SOCKS5 with Luminati

    Why should I care?
    A SOCKS server is a proxy server that works for any type of network protocol on any port and establishes a connection to a server on behalf of a user, then routes traffic between the user and the server.

    Why use SOCKS5 with Luminati?
    When you use SOCKS5 with Luminati, the proxy manager converts any requests to port 80 or port 443 to http and https requests, so you don’t have to worry about which format is accepted by your target site. With any other port, the traffic is sent as-is between the user and the host.

    Guidelines to use SOCKS5:

    • Open Luminati Proxy Manager
    • Click a port, then 'Edit Proxy'
    • Under 'General' add SOCKS port number
    • Go to "Performance" - Set Reverse Resolve: DNS
    • Add a resolve file
      • Add '--resolve PATH' to the program code
      • Follow the hosts file format
      • List domains you are going to use and their IPs
      • Add domains and IPs from the resolve file editor in the proxy manager 'tools' page

    How do I avoid subnet block range?

    What is a subnet block range?
    Smaller sections of a network are called subnets, which are useful for grouping hosts together and managing them all at once. Subnets are based on IP address, making it easy for websites or malicious users to target or block an entire subnet. For example, blocking 223 would block all IP addresses that begin with 223, while blocking 223.1 would only block IP addresses that begin with 223.1, and so on - this is the subnet block range.

    Why should I care?
    Because a database’s IPs are often all within the same subnet, they are easily blocked by websites, especially if they are known proxies.

    Avoiding subnet block range:
    Residential proxies cannot be blocked this way, because they don’t have subnet ranges. Using Luminati’s residential IPs ensures you won’t be affected if a website uses the subnet block range method.

    How to switch from API to Proxy manager

    Why should I care?
    Using the Luminati Proxy Manager offers advanced features that are not readily available in the API. Instead of having to manually code mechanisms for tasks like keeping an IP as long as possible or rotating your IP after each request, you can simply click a button in the proxy manager.

    Guidelines to to switch from API to Proxy Manager:

    1. Install the Luminati proxy manager here
    2. Change the code to send HTTP requests directly to the specified port (for example, instead of to zproxy.lum-superproxy.io:22225
    3. Configure the settings for your custom proxies and Zones through the Proxy manager dashboard. You do not need to send the user parameter (lum-customer-customer_name-zone-zone_name…) alongside your requests, as all the needed data is wrapped within the manual proxy configuration.

    How to configure Luminati raw API with iPhone

    Guidelines for configuring Luminati raw API with iPhone

    1. Open your device Settings app and go to Wi-Fi
    2. Tap the name of the Wi-Fi network you are connected to
    3. Scroll to the bottom and you will find a section for 'HTTP Proxy'. This is set to 'Off' by default. Set it to 'Manual':
      • In the server slot enter:zproxy.lum-superproxy.io
      • In the port slot enter: 22225
      • Select Authentication: DISABLE
    4. Open Browser
    5. Add the target URL
    6. In the Pop Up, tap settings
    7. Add the username (e.g. lum-customer-lum_qa-country-us-zone -city)
    8. Zone Password and tap OK

    How do I know if I’m getting cloaked?

    Why should I care?
    Getting cloaked means that you’re getting misleading information from the website you are scraping.
    Example: If you are collecting comparative competitive information to feed your automatic pricing algorithms, the target website can return artificial lower prices to your requests, to skew your pricing and profits.

    How to know when you’re getting cloaked
    When using traditional proxy networks (data center based IPs), your target websites may identify your activity quite easily and may cloak your requests. Therefore, the only way to ensure you’re not getting cloaked is to rotate your requests through residential IPs.

    Guidelines for rotating requests through millions of residential IPs:

    1. Open Luminati Proxy Manager
    2. Go to the ‘proxies’ tab
    3. Check the port of your residential zone
    4. Edit in the port settings ‘preset’ to ‘round-robin (ip) pool’
    5. Route your requests to{portnum} where the {portnum} is the port of the residential zone

    Best Practices

    General Tips

    Request Timeout

    Slower connections may get a timeout from the super-proxy server (in the header) or from the target website (in the https). To avoid timeouts set timeout period to be longer (in the request). When you do that, you may want to increase the amount of IPs that you use to send request proportionally to the change in timeout to keep the pace at which you send requests.

    Avoid getting blocked or spoofed

    • IP Country: Set the country of your IP (in the Zone) to the same country as the destination site. It makes your request look more like that of a human user, which in some cases prevents getting blocked or mislead.
    • IP City: Setting the city targeting of your IP ensures that when your Residential IP changes, the new IP will come from the same city and won't look like you traveled hundreds of kilometers in one moment, reducing the chance of getting blocked.
    • Rate Limit: When sending multiple requests via the same IP to the same destination, make sure to send up to 10 requests per day and avoid getting blocked or mislead.

    Add headers and cookies to your http/https requests

    Sometimes target sites can detect users as a bot or a crawler. In this case include headers and cookies in your http/https requests in order to mimic a human behavior.

    Use Cases

    Human Resources

    When you automatically collect public data from professional networking sites you may get an error response, followed by a JS redirect to an endpoint that sets cookies that block your IP for several hours, and then get redirected again to the login page. If the login flow is completed it means that they let you access to the requested resource. Find below some tips for collecting public data successfully with Luminati:

    Price Comparison

    While using a script for checking product prices of an online store, some of the requests may get blocked or cloaked (altered prices). In order to improve the chance to have successful requests, try out these tips:

    Product Release

    When using proxy for purchasing goods in product releases while keeping your anonymity, you'd probably want to:

    • Make many requests simultaneously
    • Speed up the requests as much as possible
    • Keep the same IP alive throughout the session of each request

    To do that using the Proxy Manager:

    In case your requests get blocked:
    • Use remote DNS. It will slow down your requests, but it costs the same and the probability that the request will go through is much higher
    • If they still get blocked, go to the Control Panel's Zones page, edit your Zone (pencil icon), and in Plan tab under Permissions choose City. Then go to the Proxy manager's proxies list and edit your port, go to Targeting, and select a country, a state, and a city. City level targeting is more expensive than the default residential country level targeting, but it significantly increases the chance of a successful request
    • Power tip: Consider switching automatically to the alternative settings mentioned above upon failure of a request using Rules, it will optimize both your results and your proxy costs

    To do that using the API:

    • Set the country of the request IP to your country with a 2-letter country code, e.g "us" = United States, to make the requests go shorter distance and arrive faster
    • Set a different session ID to each request with sequential number (1,2,3,4...) to keep previous sessions alive
    • Find fast Super-Proxies close to you by running the following command in CMD/terminal: nslookup servercountry-COUNTRY.zproxy.lum-superproxy.io
      (Replace COUNTRY with a 2-letter country code)
    • Take the Super-Proxies that you found and rotate between them with every request sent
    • Request examples:
      • First requestcurl --proxy --proxy-user lum-customer-somecompany-zone-somezone-country-us-session-0001:s0m3passw0rd "http://lumtest.com/myip.json"
      • Second requestcurl --proxy --proxy-user lum-customer-somecompany-zone-somezone-country-us-session-0002:s0m3passw0rd "http://lumtest.com/myip.json"
      • Third requestcurl --proxy --proxy-user lum-customer-somecompany-zone-somezone-country-us-session-0003:s0m3passw0rd "http://lumtest.com/myip.json"
      • Fourth requestcurl --proxy --proxy-user lum-customer-somecompany-zone-somezone-country-us-session-0004:s0m3passw0rd "http://lumtest.com/myip.json"

    Multiple Accounts

    Creating and managing many accounts from your office requires each account to behave like one person is managing it.

    • Create long single sessions by using the "Long single session (IP)" preset in the Proxy Manager, to keep the same IP throughout the session
    • If you use a bot, you can create a port in the Proxy Manager and then multiply it as many times as needed
    • When approaching more sensitive websites:
    • Here are 2 of the most popular account management softwares amongst Luminati customers:

    Mobile Setup

    Due to the nature of the residential network the IPs will rotate. Therefore, using Mobile IPs is important because target sites are less restrictive to block those IPs even though they are being changed frequently.
    When using our Mobile IPs network it is helping with increasing success rates and getting less blocked by target sites.

    • Create a new zone in the CP with mobile permissions
    • In the Proxy manager multiply ports per Exclusive residential IP
    • Rotate IP every 10-20 requests to enlarge your success rate

    Ad Verification

    Verifying that your ads are displayed and behave as intended requires to access them anonymously from various devices and locations, to click them and check the link's destination.

    • Check how many redirects there are until you reach the final landing page and adjust max requests per IP accordingly
    • Keep the same IP throughout the session by using the "Long single session (IP)" preset in the Proxy Manager
    • After verifying the final destination, automatically change IP and test again. For best results use the Proxy Manager: Create a port for each of the tests you want to carry out, and set a rule for each port that triggers the next relevant port and then the next, until the last test is done
    • Use remote DNS to perform the DNS resolution at the Proxy Peer
    • Different User Agents (browser property) give different results, so test with all the relevant User Agents one, and also sending many subsequent requests with the same User Agent may get them eventually blocked or cloaked

    Coming Soon...

    The following use-cases will be added to this Best Practices guide in the next few weeks:

    • Sales Intelligence
    • Brand Protection
    • Self-Testing
    • Data Collection

    How-to guide

    Mimic a human user

    Including all headers and cookie behavior. See bash example, using Luminati Proxy Manager:curl --proxy "http://lumtest.com/myip.json" -H 'pragma: no-cache' -H 'accept-encoding: gzip, deflate, br' -H 'accept-language: en-US,en;q=0.8' -H 'upgrade-insecure-requests: 1' -H 'user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36' -H 'accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp, image/apng,*/*;q=0.8' -H 'cache-control: no-cache' -H 'cookie: bcookie="v=somekindofcookiexxx";' -v

    How to generate bash request from your browser

    Rotate between as many unblocked IPs as possible

    Switch an IP when it gets an error, and use it again only after it cools down several hours.

    For optimal results use Luminati Exclusive residential IPs.

    To do this you have 2 options:

    1. Use our API to control the IP rotation:
      • If you use Exclusive residential IPs, get all available Exclusive residential IPs per zone: /api/get_route_vips
        curl "https://luminati.io/api/get_route_vips?" \ -H "X-Lum-Auth: lum-customer-lum_qa-zone-static-key-s6u19zy0zrys"
      • Use the IP until it gets an error (it is recommended to stop after 10 times)
      • Manage a log of blocked IPs: Document the IP and time it got an error
      • Get a different IP that didn’t get an error in the last X hours
        • Check the IP by session ID using lumtest.com or using our API
        • Check in your log when was the last time it got an error
      • Repeat this as many times as needed
    2. Use our Proxy Manager to achieve the same by setting a simple Rule:
      • Go to Edit Proxy > Rules
      • Under 'Rule Type' choose 'Status-code'i
      • Under 'Status Code string to be scanned' choose the status code that you get when the request get blocked, or choose custom and write it manually in the field that appeared below (e.g "888")
      • Under 'Action type' choose 'Retry request with new IP'
      • Under 'Number of retries' write the amount of times you want to retry sending a request using the same settings and a new IP

    Port Rules

    Port Rules allow you to define a custom action for specific request response.
    Use Port Rules to automatically switch from one port to another in case of a failed request.Consider using the Luminati waterfall approach or building other rule sets, in order to maximize request success rate and reduce the price you pay.

    Remote DNS

    Using Remote DNS gives you a DNS resolve server similar to that of the Proxy peer (the origin of the Proxy's IP). This makes your request look more credible as the resolve server is usually located geographically close to the IP, whereas without using Remote DNS the resolve server is one of Luminati's Super-Proxies which may be located in another country. To use Remote DNS:

    • Via Proxy Manager, go to Proxies tab > Edit Proxy > Request Speed tab > set "DNS Lookup" to "Remote - resolved by peer"
    • Via API simply add it to your username string. For example:lum-customer-[ACCOUNTID]-zone-[VIPZONE]-dns-remote

    Make multiple copies of a port in the Proxy Manager

    • Create as many duplicates of the proxy that you created as you need. Click Edit (pencil icon) on the proxy that you created, then go to "General" tab, and under "Multiply" write the amount of times that you want the proxy to be duplicated.
    • You can then download the proxies list (contains IPs and ports) by clicking the CSV button that's on the top of the list.