API Documentation

Jump to section

Search
  • ZONE - The zone name for which you want to get the info. view my Zones
  • CUSTOMER - Your account id which you can get from your control panel
  • PASSWORD - Your zone password. view my Zones
  • COUNTRY - The country code you wish to filter the request. (e.g '-country-us' for United states)
  • username - the email address which you use for login
  • password - the account login password
Choose language:
Shell
Node.js

Statistics API

Get the bandwith stats for a Zone

API endpoint:GET /api/zone/bw

Copy
curl "https://luminati.io/api/zone/bw" -u "username:password"
Copy
curl "https://luminati.io/api/zone/bw?customer=CUSTOMER&zone=ZONE&details=1" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: details=1

Get the bandwith stats for all your Zones

API endpoint:GET /api/customer/bw

Copy
curl "https://luminati.io/api/customer/bw" -u "username:password"
Copy
curl "https://luminati.io/api/customer/bw?customer=CUSTOMER&details=1" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"

Get the total cost and bandwith stats for a Zone

API endpoint:GET /api/zone/cost

Copy
curl "https://luminati.io/api/zone/cost" -u "username:password"
Copy
curl "https://luminati.io/api/zone/cost?customer=CUSTOMER&zone=ZONE" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"

Request Logs API

Get request logs for customer

API endpoint:GET /api/customer/req_logs

Optional parameters:page=1&page_size=100
zone=&status.code=&status.message=&tun.session=
ts.from=&ts.to=&ua=&dst.host=&dst.url=
Copy
curl "https://luminati.io/api/customer/req_logs?customer=CUSTOMER" -u "username:password"
Sample Response: ["request obj 1","request obj2"]

Get request logs for customer

API endpoint:GET /api/customer/req_logs/stats

Optional parameters:status_breakdown=1
zone=&status.code=&status.message=&tun.session=
ts.from=&ts.to=&ua=&dst.host=&dst.url=
Copy
curl "https://luminati.io/api/customer/req_logs/stats?customer=CUSTOMER" -u "username:password"
Sample Response: {"total":100,"success_statuses":99,"status_breakdown":[]}

Manage your proxies API

Get amount of available IPs

API endpoint:GET /api/zone/count_available_ips

Copy
curl "https://luminati.io/api/zone/count_available_ips?customer=CUSTOMER&zone=ZONE[&plan={...}]" -u "username:password"
Paramseters:
  • customer=CUSTOMER[string] - your account id which you can get from your control panel (required)
  • zone=ZONE[string] - name of the Zone (required)
  • plan={...}[JSON object] - abstract plan parameters
    • ips_type=shared|selective[string] - type of the IPs
    • country=country_name[string] - IPs location country
    • country_city=country_name-city_name[string] - defines the city location of the IPs
    • city=true[boolean] - requred with [country_city] parameter
    • exclusive_sec=1234[string] - cooling period in seconds
    • domain_whitelist=d1.com d2.com d3...[string] - space separated list of domains. Note that for [curl] the spaces should be urlencoded (d1.com%20d2.com)
    • geo_db={...}[JSON object] - turns on/off using of the IP`s location databases
      • maxmind=true[boolean] - use this IP location DB
      • dbip=true[boolean] - use this IP location DB
      • google=true[boolean] - use this IP location DB
      • ip2location=true[boolean] - use this IP location DB
Sample Response: {count: 1234}
Examples:
Available IPs for current Zone plan:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE" -u "username:password"
Abstract plan, exclusive IPs:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"ips_type\":\"selective\"\}" -u "username:password"
Abstract plan, shared IPs located in Unated States:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"country\":\"us\",\"ips_type\":\"shared\"\}" -u "username:password"
abstract plan, exclusive ips located in unated states:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"country\":\"us\",\"ips_type\":\"selective\"\}" -u "username:password"
abstract plan, exclusive ips located in unated states, cooling period: 10 days:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"country\":\"us\",\"ips_type\":\"selective\",\"exclusive_sec\":864000\}" -u "username:password"
Abstract plan, shared IPs located in Unated States, Denver:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"ips_type\":\"shared\",\"country_city\":\"us-denver\",\"city\":true\}" -u "username:password"
Abstract plan, shared IPs located in US, exclusive for domains: amazon.com, fb.com:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"ips_type\":\"selective\",\"country\":\"us\",\"domain_whitelist\":\"amazon.com fb.com\"\}" -u "username:password"
Abstract plan, shared IPs located in US, geo IP databases: should persist in both: maxmind and dbip:
Copy
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"ips_type\":\"shared\"\},\"country\":\"us\",\"geo_db\":\{\"maxmind\":true,\"dbip\":true\}" -u "username:password"

Get recent IPs attempting to use a Zone

API endpoint:GET /api/zone/recent_ips

Copy
curl "https://luminati.io/api/zone/recent_ips?customer=CUSTOMER&zones=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/recent_ips" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: {"ZONE":["255.0.0.127","10.0.0.1"]}

Get recent IPs attempting to use any of your Zones

API endpoint:GET /api/zone/recent_ips

Copy
curl "https://luminati.io/api/zone/recent_ips?customer=CUSTOMER&zones=*" -u "username:password"
Sample Response: {"ZONE_1":["255.0.0.127","10.0.0.1"],"ZONE_2":["255.0.0.127","10.0.0.1"]}

Get the available Data center/Static REsidential IPs for a country

API endpoint:GET /api/zone/route_ips

Copy
curl "https://luminati.io/api/zone/route_ips?customer=CUSTOMER&zone=ZONE&country=COUNTRY" -u "username:password"
Copy
curl "https://luminati.io/api/zone/route_ips" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD-country-COUNTRY"
Sample Response: 10.0.0.0/24

Get all the available Data center/Static REsidential IPs

API endpoint:GET /api/zone/route_ips

Copy
curl "https://luminati.io/api/zone/route_ips?customer=CUSTOMER&zone=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/route_ips" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
NOTE: add to the request '?expand=1' if you wish to expand the IPs in the response.
Sample Response: 11.0.0.1-11.0.0.8

Get all available gIPs per Zone

API endpoint:GET /api/zone/route_vips

Copy
curl "https://luminati.io/api/zone/route_vips?customer=CUSTOMER&zone=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/route_vips" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: ["us_7922_fl_hollywood_0","ma_36903_01_tetouan_5","br_52894_mg_montesclaros_99","tr_9121_07_antalya_10"]

Account management API

Get total balance through API

API endpoint:GET /api/customer/balance

Copy
curl "https://luminati.io/api/customer/balance?customer=CUSTOMER" -u "username:password"
Sample Response: {"balance":456,"pending_costs":123}
The value under balance shows the amount of money in your account.
The value under pending_costs shows the amount of money you will be billed for, as of this moment, in the next billing cycle

Get Zone info

API endpoint:GET /api/zone

Copy
curl "https://luminati.io/api/zone?customer=CUSTOMER&zone=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: {"ips":"any","password":["PASSWORD"],"plans":[{"start":"2019-07-15T18:08:59.269Z","type":"static","ips_type":"shared","ip_alloc_preset":"shared_block","bandwidth":"payperusage"}]}

Add a Zone

API endpoint:POST /api/zone

Parameters:
  • zone: object containingname (required), ips (whitelist) andpassword (string or array for multiple passwords).
  • plan: object containing plan options (their respective valid options can be seen in the example).
Copy
curl -X POST "https://luminati.io/api/zone" -H "Content-Type: application/json" -d '{"zone":{"name":"zone291231237"},"customer":"test_user","plan":{"type":"static|resident","ips_type":"shared|dedicated|selective","ip_alloc_preset":"shared_block","bandwidth":"payperusage|unlimited","mobile":false,"city":false,"asn":false,"vip":false,"vips_type":"shared|vip|domain|domain_p","vips":0,"domain_whitelist":"test.com fb.com","not_country":null,"vip_country":"any","exclusive_sec":0,"exclusive_type":"days","exclusive_num":0,"ips":0}}' -u "username:password"
Request response will show the sanitized Zone.
Sample Response: {"plan":{"start":"2019-07-15T18:08:59.269Z","type":"static","ips_type":"shared","ip_alloc_preset":"shared_block","bandwidth":"payperusage"},"zone":{"ips":"any","password":["PASSWORD"],"plans":[{"start":"2019-07-15T18:08:59.269Z","type":"static","ips_type":"shared","ip_alloc_preset":"shared_block","bandwidth":"payperusage"}]}}

Remove Zone

API endpoint:DELETE /api/zone

Copy
curl -X DELETE "https://luminati.io/api/zone" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE"}' -u "username:password"

Get Zone passwords

API endpoint:GET /api/zone/passwords

Copy
curl "https://luminati.io/api/zone/passwords?customer=CUSTOMER&zone=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/passwords" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: {"passwords":["psw1","psw2"]}

Get Zone permissions

API endpoint:GET /api/zone/permissions

Copy
curl "https://luminati.io/api/zone/permissions?customer=CUSTOMER&zone=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/permissions" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: {"perms":["city","google"]}

Get Zone status

API endpoint:GET /api/zone/status

Copy
curl "https://luminati.io/api/zone/status?customer=CUSTOMER&zone=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/status" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: {"status":"active"}

Get Zone datacenter IPs

API endpoint:GET /api/zone/ips

Copy
curl "https://luminati.io/api/zone/ips?customer=CUSTOMER&zone=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/ips" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Request response will output all allocated IPs in the Zone including their respective country per database.
Sample Response: {"ips":[{"ip":"1.1.1.1","maxmind":"au","ext":{"dbip":"au","ip2location":"au","google":"us"}},{"ip":"1.1.1.1","maxmind":"au","ext":{"dbip":"au","ip2location":"au","google":"us"}}]}

Add IPs

API endpoint:POST /api/zone/ips

Optional parameters:
  • country: new IPs' country (e.g. us)
  • country_city: new IPs' city (e.g. us-chicago)
Copy
curl -X POST "https://luminati.io/api/zone/ips" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","count":2}' -u "username:password"
Request response will output all allocated IPs in the Zone including the added IPs.
Sample Response: {"ips":["1.1.1.1","1.1.1.2"],"new_ips":["1.1.1.1"]}

Remove datacenter IPs

API endpoint:DELETE /api/zone/ips

Copy
curl -X DELETE "https://luminati.io/api/zone/ips" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","ips":["ip1","ip2"]}' -u "username:password"
Request response will output the IPs removed.
Sample Response: {"ips":["ip1","ip2"]}

Remove residential gIPs

API endpoint:DELETE /api/zone/vips

Copy
curl -X DELETE "https://luminati.io/api/zone/vips" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","vips":["vip1","vip2"]}' -u "username:password"
Request response will output the gIPs removed.
Sample Response: {"vips":["us_7922_fl_hollywood_0","ma_36903_01_tetouan_0"]}

Refresh residential gIPs

API endpoint:POST /api/zone/ips/refresh

Copy
curl -X POST "https://luminati.io/api/zone/ips/refresh" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","vips":["vip1","vip2"]}' -u "username:password"
Request response will output all allocated gIPs in the Zone including the refreshed gIPs.
Sample Response: {"vips":[{"vip":"tr_9121_07_antalya_10","country":"tr"},{"vip":"tr_9121_07_antalya_17","country":"tr"}]}
Each gIP refreshed costs $0.02/refresh/IP

Refresh datacenter IPs

API endpoint:POST /api/zone/ips/refresh

Optional parameters:
  • country: new IPs' country (e.g. us)
  • country_city: new IPs' city (e.g. us-chicago)
Copy
curl -X POST "https://luminati.io/api/zone/ips/refresh" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","ips":["ip1","ip2"]}' -u "username:password"
Request response will output all allocated IPs in the Zone including the refreshed IPs.
Sample Response: {"ips":["1.1.1.1","1.1.1.2"],"new_ips":["1.1.1.1"]}
If ALL IPs refresh needed, then ips parameter should be omitted. See pricing for refreshing datacenter IPs

Switch 100% uptime ON/OFF in zone

API endpoint:POST /api/zone/switch_100uptime

Parameters:
  • activate '100% uptime': "active":1
  • disable '100% uptime': "active":0
Copy
curl -X POST "https://luminati.io/api/zone/switch_100uptime" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","active":1}' -u "username:password"

Get peers IPs

API endpoint:GET /api/get_peers

Optional parameters:
  • zone: filter by Zone
  • country: filter by country
  • asn: filter by ASN (Autonomous System Number)
  • vip: filter by VIP number
Copy
curl "https://luminati.io/api/get_peers" -u "username:password"
The response will output all available peers IPs considering provided filters. The peers permission is required.

Add domain to Zone whitelist/blacklist

API endpoint:POST /api/zone/domain_perm

TYPE can bewhitelist or blacklist.
Copy
curl -X POST "https://luminati.io/api/zone/domain_perm" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","type":"TYPE","domain":"example.org"}' -u "username:password"
Request response will output domains whitelist and blacklist in the Zone including the added domain.
Sample Response: {"whitelist":["test.com","example.org"]}

Remove domain from Zone whitelist/blacklist

API endpoint:DELETE /api/zone/domain_perm

TYPE can bewhitelist or blacklist.
Copy
curl -X DELETE "https://luminati.io/api/zone/domain_perm" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","type":"TYPE","domain":"test.com"}' -u "username:password"
Request response will output domains whitelist and blacklist in the Zone excluding the removed domain.
Sample Response: {"whitelist":["example.org"]}

Turn on/off Zone

API endpoint:POST /api/zone/change_disable

Copy
curl -X POST "https://luminati.io/api/zone/change_disable" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","disable":1}' -u "username:password"

Get account status

API endpoint:GET /api/status

Copy
curl "https://luminati.io/api/status?customer=CUSTOMER" -u "username:password"
Copy
curl "https://luminati.io/api/status" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: {"status":"active"}

Change account status

API endpoint:PUT /api/status

Copy
curl -X PUT "https://luminati.io/api/status" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","status":"STATUS"}' -u "username:password"
STATUS can besuspend_manual or active.

Get a list of whitelisted IPs for a specific Zone

API endpoint:GET /api/zone/whitelist

Copy
curl "https://luminati.io/api/zone/whitelist?customer=CUSTOMER&zones=ZONE" -u "username:password"
Copy
curl "https://luminati.io/api/zone/whitelist" -H "X-Hola-Auth: lum-customer-CUSTOMER-zone-ZONE-key-PASSWORD"
Sample Response: {"ZONE":["any","127.0.0.1"]}

Get a list of whitelisted IPs for all your Zones

API endpoint:GET /api/zone/whitelist

Copy
curl "https://luminati.io/api/zone/whitelist?customer=CUSTOMER&zones=*" -u "username:password"
Sample Response: {"ZONE1":["any","127.0.0.1"],"ZONE2":["any"]}

Add IP to Zone whitelist

API endpoint:POST /api/zone/whitelist

Copy
curl -X POST "https://luminati.io/api/zone/whitelist" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","ip":"1.2.1.2"}' -u "username:password"

Remove IP from Zone whitelist

API endpoint:DELETE /api/zone/whitelist

Copy
curl -X DELETE "https://luminati.io/api/zone/whitelist" -H "Content-Type: application/json" -d '{"customer":"CUSTOMER","zone":"ZONE","ip":"1.2.1.2"}' -u "username:password"

Others

Get current service status

API endpoint:GET /api/network_status/NETWORK_TYPE

Copy
curl "https://luminati.io/api/network_status/NETWORK_TYPE" -u "username:password"
NETWORK_TYPE can be one of:
  • All: all
  • Residential: res
  • Datacenter: dc
  • Mobile: mobile
Sample Response: {"status":true}

Get country cities

API endpoint:GET /api/cities

Copy
curl "https://luminati.io/api/cities?country=US" -u "username:password"

Using different coding languages

Which coding languages can be used?

All API examples for account management are presented using Shell but can be used in a variety of coding languages.
To find all available coding languages check out the Account management section of our API and examples page

Networks
DatacenterStatic ResidentialResidentialMobileSuper ProxyLocations
Tools
APILPMUnblockerChrome ExtensionData Collection Automation
Use Cases
E-commerceTravelAd VerificationBrand ProtectionSEOWeb Data ExtractionWebsite Testing
Programs
Referral ProgramAccelerator ProgramReward ProgramLuminati SDKPartnersCOVID-19 Research
Learning Center
API DocumentationFAQWebinarsIntegrationsLearning HubSLA
Company
BlogNewsEventsCase StudiesTestimonialsEthical UsageCareersAbout
Legal
Privacy PolicyCookie PolicyLicenseReport abusePatentsESG
© Copyright 2020 Luminati Networks Ltd. | All rights reserved

Business continuity at Luminati: Keeping our customers up and running during COVID-19

See Statement
Certified by: