API and examples



How to use the Luminati API


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

Using the system — Overview

  • 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 the Proxy Peer should be in, when to force a switch to a different IP address within the country, and set other parameters.
  • The control is done by -country-CODE suffixes after username.
    Example for Brasil: {{zone.username}}-country-br

Obtaining adresses of Super Proxies

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

Additional options for obtaining Super Proxies

  • For shorter latency to the Super Proxies, you can use the following template: servercountry-{country}.zproxy.luminati.io. To resolve to super proxies in the Great Britain, you can use the following hostname: servercountry-gb.zproxy.luminati.io. We currently support the following countries: {{super_proxy_countries.join(', ')}}. Please note that this does not restrict the IPs chosen country but will simply improve performances by using Super Proxies which have shorter roundtrips relative to your current location.
  • To refresh the set of Super Proxies, use customer-{{data.customer.customer_name }}-session-12345.zproxy.luminati.io where 12345 is a new unique number every time. You can combine servercountry and session: customer-{{data.customer.customer_name }}-session-12345-servercountry-gb.zproxy.luminati.io

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: {{zone.username}}-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.
  • 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.
  • Use the same super proxy by storing the IP used from a DNS request to zproxy.luminati.io, if you don't use the same super proxy you won't be able to keep the same proxy peer IP.
  • If an assigned Proxy Peer becomes unavailable, the Super Proxy will change it automatically, 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 HTTP the IP is in the response header x-hola-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-hola-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

Super Proxy status

  • To “ping” the Super Proxy status:
    You will receive its version number, IP, country where it's located, and whether it is “connected” to the Luminati network.

Increasing performance

  • Reduce round-trip/latency:
    • Choose Proxy Peer IP via {{zone.username}}-country-br (Brazil for example) matching the destination site you connect to.
    • Use Super Proxies close to your location by using full name servercountry-us.zproxy.luminati.io (Super Proxies located in United States for example, see Additional options for obtaining Super Proxies).
  • Increase throughput: Run multiple parallel sessions with unique session IDs, from the same Client, where each session will be assigned a unique Proxy Peer using distinct session IDs.

Controlling where DNS resolution is performed

  • If you use {{zone.username}}-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 {{zone.username}}-dns-remote. This is slower, but will give you the same IP as users in your chosen country receive.

Country-specific proxy peer IP

  • Example for United States: {{zone.username}}-country-us

City-specific proxy peer IP

  • Example for Los Angeles, United States: {{zone.username}}-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: {{zone.username}}-asn-1234

Mobile proxy peer IP

  • Use mobile ip: {{zone.username}}-mobile-true or {{zone.username}}-mobile
  • Don't use mobile ip: {{zone.username}}-mobile-false

Changing Proxy Peer IP when using a browser or browser automation

  • Changing an Proxy Peer IP in Luminati is done by changing the -session-rand93849 part in the proxy username to a new random number.
    There are two problems with browsers: they cache the proxy username, and sites may use cookies or local storage in your browser to identify the same user even after an IP change.
  • To solve the proxy username caching problem, open this URL in the browser:
    Make sure to change only the username: {{zone.username}}-session-rand39484 to the username in use by the browser.
    Do not change the protocol or the site since then that command will be visible servers outside hola, and might expose your scraping your use of Luminati, http://trigger.domain is a special domain name that is handled by the super-proxy.
  • To solve the cookies and local storage problem, use the commands in the browser's options menu to clear cookies and local storage, or install a browser extension for cleaning those in one click. Some browsers also have a Private or Incognito mode which makes sure that cookies and local storage are purged when the window is closed.

Using luminati in standard windows 10 settings

  • Get your proxy address
    zproxy.luminati.io:22225 for direct access for LPM
  • 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 (zprxoy.luminati.io or in appropriate fields
  • Click OK
  • Some applications will interfere with setting up the proxy settings, if the proxy does not work and settings are reseting, look for a proxy/vpn related application and disable it.
  • 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.luminati.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.luminati.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.luminati.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.



  • {{ex.desc}}: /api/{{ex.endpoint}}
    Sample Response:

The API cannot be used in a browser. To view the information, use the web interface.