API documentation

  • 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
Java
C#
VB
PHP
Python
Ruby
Perl

Using Luminati's Proxies

Usage example

curl --proxy zproxy.lum-superproxy.io:22225 --proxy-user lum-customer-CUSTOMER-zone-ZONE-country-COUNTRYundefined:PASSWORD "http://lumtest.com/myip.json"

Statistics API

Get the bandwith stats for a Zone

API endpoint:GET /api/zone/bw

curl "https://luminati.io/api/zone/bw" -u "username:password"
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

curl "https://luminati.io/api/customer/bw" -u "username:password"
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

curl "https://luminati.io/api/zone/cost" -u "username:password"
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=
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=
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

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:
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE" -u "username:password"
Abstract plan, exclusive IPs:
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:
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:
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:
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:
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:
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:
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

curl "https://luminati.io/api/zone/recent_ips?customer=CUSTOMER&zones=ZONE" -u "username:password"
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

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

curl "https://luminati.io/api/zone/route_ips?customer=CUSTOMER&zone=ZONE&country=COUNTRY" -u "username:password"
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

curl "https://luminati.io/api/zone/route_ips?customer=CUSTOMER&zone=ZONE" -u "username:password"
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

curl "https://luminati.io/api/zone/route_vips?customer=CUSTOMER&zone=ZONE" -u "username:password"
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

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

curl "https://luminati.io/api/zone?customer=CUSTOMER&zone=ZONE" -u "username:password"
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).
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

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

curl "https://luminati.io/api/zone/passwords?customer=CUSTOMER&zone=ZONE" -u "username:password"
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

curl "https://luminati.io/api/zone/permissions?customer=CUSTOMER&zone=ZONE" -u "username:password"
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

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

Get active Zones

API endpoint:GET /api/zone/get_active_zones

curl "https://luminati.io/api/zone/get_active_zones?customer=CUSTOMER" -u "username:password"
Sample Response: [{"name":"ZONE1","type":"dc"}]

Get Zone datacenter IPs

API endpoint:GET /api/zone/ips

curl "https://luminati.io/api/zone/ips?customer=CUSTOMER&zone=ZONE" -u "username:password"
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)
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

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

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

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/Static residential 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)
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
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
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.

Get all peers

API endpoint:GET /api/get_peers/all

The response will output all available peers IPs. The peers_all permission is required.
curl "https://luminati.io/api/get_peers/all" -u "username:password"

Add domain to Zone whitelist/blacklist

API endpoint:POST /api/zone/domain_perm

TYPE can bewhitelist or blacklist.
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.
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

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

curl "https://luminati.io/api/status?customer=CUSTOMER" -u "username:password"
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

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

curl "https://luminati.io/api/zone/whitelist?customer=CUSTOMER&zones=ZONE" -u "username:password"
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

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

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

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

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

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