API documentation

Jump to section

  • 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)
  • API_TOKEN — The token which you (or your account admin) created in account settings
  • If you're looking for documentation about using proxies, follow this link.
Choose language
Shell
Node.js
Java
C#
Python

Authentication via username and password will be deprecated on 01-Jan-2021. Please switch to tokens.

Statistics API

Get the bandwith stats for a Zone

API endpoint:GET /api/zone/bw

curl "https://luminati.io/api/zone/bw" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/bw?customer=CUSTOMER&zone=ZONE&details=1" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/customer/bw?customer=CUSTOMER&details=1" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/cost?customer=CUSTOMER&zone=ZONE" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
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" -H "Authorization: Bearer API_TOKEN"
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={...}]" -H "Authorization: Bearer API_TOKEN"
Parameters:
  • 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" -H "Authorization: Bearer API_TOKEN"
Abstract plan, exclusive IPs:
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"ips_type\":\"selective\"\}" -H "Authorization: Bearer API_TOKEN"
Abstract plan, shared IPs located in United States:
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"country\":\"us\",\"ips_type\":\"shared\"\}" -H "Authorization: Bearer API_TOKEN"
abstract plan, exclusive ips located in United States:
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"country\":\"us\",\"ips_type\":\"selective\"\}" -H "Authorization: Bearer API_TOKEN"
abstract plan, exclusive ips located in United 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\}" -H "Authorization: Bearer API_TOKEN"
Abstract plan, shared IPs located in United States, Denver:
curl "https://luminati.io/api/count_available_ips?customer=CUSTOMER&zone=ZONE&plan=\{\"ips_type\":\"shared\",\"country_city\":\"us-denver\",\"city\":true\}" -H "Authorization: Bearer API_TOKEN"
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\"\}" -H "Authorization: Bearer API_TOKEN"
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\}" -H "Authorization: Bearer API_TOKEN"

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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/recent_ips" -H "X-Lum-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=*" -H "Authorization: Bearer API_TOKEN"
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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/route_ips" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/route_ips" -H "X-Lum-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 Exclusive residential IPs per Zone

API endpoint:GET /api/zone/route_vips

curl "https://luminati.io/api/zone/route_vips?customer=CUSTOMER&zone=ZONE" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/route_vips" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN" -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}}'
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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE"}'

Get Zone passwords

API endpoint:GET /api/zone/passwords

curl "https://luminati.io/api/zone/passwords?customer=CUSTOMER&zone=ZONE" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/passwords" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/permissions" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/status" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN"
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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/ips" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","count":2}'
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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","ips":["ip1","ip2"]}'
Request response will output the IPs removed.
Sample Response: {"ips":["ip1","ip2"]}

Remove Exclusive residential IPs

API endpoint:DELETE /api/zone/vips

curl -X DELETE "https://luminati.io/api/zone/vips" -H "Content-Type: application/json" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","vips":["vip1","vip2"]}'
Request response will output the Exclusive residential IPs removed.
Sample Response: {"vips":["us_7922_fl_hollywood_0","ma_36903_01_tetouan_0"]}

Refresh Exclusive residential IPs

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

curl -X POST "https://luminati.io/api/zone/ips/refresh" -H "Content-Type: application/json" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","vips":["vip1","vip2"]}'
Request response will output all allocated Exclusive residential IPs in the Zone including the refreshed Exclusive residential IPs.
Sample Response: {"vips":[{"vip":"tr_9121_07_antalya_10","country":"tr"},{"vip":"tr_9121_07_antalya_17","country":"tr"}]}
Each Exclusive residential IP 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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","ips":["ip1","ip2"]}'
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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","active":1}'

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" -H "Authorization: Bearer API_TOKEN"
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" -H "Authorization: Bearer API_TOKEN"

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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","type":"TYPE","domain":"example.org"}'
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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","type":"TYPE","domain":"test.com"}'
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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","disable":1}'

Get account status

API endpoint:GET /api/status

curl "https://luminati.io/api/status?customer=CUSTOMER" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/status" -H "X-Lum-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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","status":"STATUS"}'
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" -H "Authorization: Bearer API_TOKEN"
curl "https://luminati.io/api/zone/whitelist" -H "X-Lum-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=*" -H "Authorization: Bearer API_TOKEN"
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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","ip":"1.2.1.2"}'

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" -H "Authorization: Bearer API_TOKEN" -d '{"customer":"CUSTOMER","zone":"ZONE","ip":"1.2.1.2"}'

Others

Get current service status

API endpoint:GET /api/network_status/NETWORK_TYPE

curl "https://luminati.io/api/network_status/NETWORK_TYPE" -H "Authorization: Bearer API_TOKEN"
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" -H "Authorization: Bearer API_TOKEN"

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 API Examples section in your account.

Proxy types
Data center proxiesStatic residential proxiesRotating residential proxiesMobile residential proxiesList of locations
Products
Data collection automation (DCA)Data unblockerProxy managerBrowser extension
Use cases
E-commerceTravelAd verificationBrand protectionSEOWeb data extractionWebsite testing
Programs
Referral programAccelerator programReward programLuminati SDKPartnersCOVID-19 research
Learning center
API documentationFAQWebinarsIntegrationsLearning hubSLA
Company
BlogNewsEventsCase studiesTestimonialsSuper proxyEthical usageCareersAbout
Legal
Privacy policyCookie policyLicenseReport abusePatentsESG
© Copyright 2020 Luminati Networks Ltd. | All rights reserved
Certified by: