Residential proxies
Rotating residential IPs from devices whose owners opted in through the DataFuel SDK. Rotate on every request or hold a session for up to 24 hours. Billed per GB, traffic never expires.
- Rotating by default, sticky sessions up to 24 hours
- Country, region, city, ASN and OS targeting; multiple countries in one request
- HTTP, HTTPS and SOCKS5, with UDP on a verified pool
- Billed per GB used; traffic never expires; no monthly minimum
Gateways
Connect to the gateway closest to your servers. The gateway’s region does not affect which IPs you get; targeting decides that.
| Region | Host |
|---|---|
| Europe: | gw-eu.datafuel.ai |
| United States: | gw-us.datafuel.ai |
| Asia: | gw-as.datafuel.ai |
Ports
| Port | Protocols | Use it for |
|---|---|---|
5555: | HTTP, HTTPS, SOCKS5 over TCP and UDP | The default. Works for everything, including SOCKS5 UDP |
7777: | HTTP, HTTPS | Clients that only speak HTTP proxies |
1080: | SOCKS5 over TCP only | Clients that expect the conventional SOCKS port |
For SOCKS5 with UDP, use port 5555 and the UDP pool described below.
Authentication
username:password. The password is fixed per account; the username carries your targeting. Both are in the dashboard under Proxies, or from the User API.
network-residential-country-us-session-4695243273-ttl-10:YOUR_PASSWORD
⟧ The username
The username is a list of key-value pairs joined by hyphens. It starts with the pool selector; everything after it narrows the IP.
network-residential-country-gb-region-england-city-london-session-39yrj3-ttl-60
└── pool ─────────┘└───────── where the IP comes from ─────────┘└── how long you keep it ──┘
⟧ | Pool | Username starts with |
|---|---|
| Residential, desktop devices: | network-residential |
| Residential, UDP-verified IPs: | network-residential-pool-udp |
Leave a parameter out and the network chooses for you. The full list, with rules on what combines with what, is in Targeting. Carrier IPs are a separate plan with its own credentials; see Mobile proxies.
Rotating versus sticky
Rotating. Omit session and every request gets a new IP.
curl --proxy gw-eu.datafuel.ai:5555 \
--proxy-user network-residential-country-gb:$PASSWORD \
https://ipinfo.io/json
⟧ Sticky. Add session-<id> with any id you choose, and every request carrying that id uses the same IP. Add ttl-<minutes> to say how long the IP is held; without it the session uses the default lifetime. The maximum is 1440 minutes, 24 hours.
curl --proxy gw-eu.datafuel.ai:5555 \
--proxy-user network-residential-country-gb-session-2836298-ttl-60:$PASSWORD \
https://ipinfo.io/json
⟧ Use a different session id for every identity you need to keep apart. When the TTL expires or the IP goes offline, the next request with the same id gets a new IP.
Examples
Country and city
curl --proxy gw-eu.datafuel.ai:5555 \
--proxy-user network-residential-country-gb-region-england-city-london-session-39yrj3:$PASSWORD \
https://ipinfo.io/json
⟧ Country and region
curl --proxy gw-us.datafuel.ai:5555 \
--proxy-user network-residential-country-us-region-texas-session-39yrj3:$PASSWORD \
https://ipinfo.io/json
⟧ Several countries at once. The IP comes from any of them.
curl --proxy gw-eu.datafuel.ai:5555 \
--proxy-user network-residential-country-de,gb,us:$PASSWORD \
https://ipinfo.io/json
⟧ A specific carrier or ISP, by ASN
curl --proxy gw-eu.datafuel.ai:5555 \
--proxy-user network-residential-country-de-asn-3320-session-7288t722:$PASSWORD \
https://ipinfo.io/json
⟧ Operating system of the device
curl --proxy gw-eu.datafuel.ai:5555 \
--proxy-user network-residential-country-de-os-windows-session-7288t722:$PASSWORD \
https://ipinfo.io/json
⟧ UDP traffic. The pool-udp pool contains only IPs that passed a per-IP test for UDP over SOCKS5.
curl --proxy socks5h://gw-eu.datafuel.ai:5555 \
--proxy-user network-residential-pool-udp-country-de-session-7288t3722:$PASSWORD \
https://ipinfo.io/json
⟧ In your code
Python, requests
import requests
proxy = "http://network-residential-country-us-session-a91f3:PASSWORD@gw-us.datafuel.ai:5555"
r = requests.get("https://ipinfo.io/json", proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.json())
⟧ Node.js, fetch with undici
import { ProxyAgent, fetch } from "undici";
const dispatcher = new ProxyAgent(
"http://network-residential-country-us-session-a91f3:PASSWORD@gw-us.datafuel.ai:5555"
);
const res = await fetch("https://ipinfo.io/json", { dispatcher });
console.log(await res.json());
⟧ Go, net/http
proxyURL, _ := url.Parse("http://network-residential-country-us-session-a91f3:PASSWORD@gw-us.datafuel.ai:5555")
client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)}}
res, _ := client.Get("https://ipinfo.io/json")
⟧ Write the username exactly as in the curl examples; URL-encode the password if it contains reserved characters.
Buying and managing
Residential traffic is bought in GB and never expires. Buy, top up, generate proxies and read usage from the dashboard or with the User API, described below.
Managing the plan with the User API
Everything the dashboard does for a plan is also available at https://api.datafuel.ai with an API key sent as Authorization: Bearer df_live_…. Read operations need the api.residential.read scope; reading credentials or generating proxies needs api.residential.manage. Full reference: Residential proxies · User API.
1. Find the plan id. Plans are listed newest first with the traffic left on each. You hold at most one plan per product; the residential plan is the one whose product is residential traffic.
curl https://api.datafuel.ai/api/v1/residential/plans \
--header "Authorization: Bearer $API_KEY"
⟧ {
"results": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Residential proxies",
"status": "active",
"traffic": { "total_gb": 100, "used_gb": 12.4, "remaining_gb": 87.6 }
}
]
}
⟧ Reference: List your plans.
2. Check what the plan can target. Get a plan returns the plan with a targeting block: which of region, city and asn it accepts, whether sticky sessions and session_minutes are allowed, and the operating systems os can name. A field the plan cannot target is refused with 400.
curl https://api.datafuel.ai/api/v1/residential/plans/$PLAN \
--header "Authorization: Bearer $API_KEY"
⟧ {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Residential proxies",
"status": "active",
"targeting": {
"region": true,
"city": true,
"asn": true,
"sticky": true,
"session_minutes": true,
"os": ["windows", "macos", "linux", "android", "ios"],
"os_multiple": false
}
}
⟧ Reference: Get a plan.
3. Find region, city and ASN codes. The region and city values in a username are codes, not free text. Ask the plan for the codes in a country, optionally filtered by region or by a search term; the answer carries at most 200 of each.
curl "https://api.datafuel.ai/api/v1/residential/plans/$PLAN/locations?country=US&search=los" \
--header "Authorization: Bearer $API_KEY"
⟧ {
"country": "US",
"regions": [ { "code": "california", "name": "California" } ],
"cities": [ { "code": "losangeles", "name": "Los Angeles" } ]
}
⟧ Use the code values in the username: region-california-city-losangeles. Reference: List regions and cities.
ASNs have their own list. List ASNs searches by name or number and answers with at most 200. The list is global, not per country, so pick one that operates where your proxies exit.
curl "https://api.datafuel.ai/api/v1/residential/plans/$PLAN/asns?search=comcast" \
--header "Authorization: Bearer $API_KEY"
⟧ {
"asns": [ { "code": "7922", "name": "Comcast Cable Communications" } ]
}
⟧ Use the code as asn-7922 in a username. asn cannot be combined with city. Reference: List ASNs.
4. Generate ready-made proxies. Instead of composing usernames yourself, ask the plan for quantity proxies with the targeting you need. Each comes back with the right gateway for its country, a username carrying the targeting and a session, and the plan’s password. Nothing is created or charged by this call. Without country, each proxy exits in a random country of the plan.
curl https://api.datafuel.ai/api/v1/residential/plans/$PLAN/proxies \
--request POST \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"country": "US",
"region": "california",
"city": "losangeles",
"rotation": "sticky",
"session_minutes": 60,
"quantity": 5,
"format": "json"
}'
⟧ {
"proxies": [
{
"host": "gw-us.datafuel.ai",
"port": 5555,
"username": "network-residential-country-us-region-california-city-losangeles-session-8f2a91-ttl-60",
"password": "…",
"country": "US"
}
]
}
⟧ rotation is rotating (the default: a new IP between requests) or sticky (each proxy keeps its IP for session_minutes). format: txt returns one host:port:username:password per line, ready to paste into a tool. Reference: Generate proxies.
asn exits through one carrier or ISP, in place of city, and os lists the operating systems the exit device may run, such as ["windows"]; it takes more than one only when the plan’s targeting.os_multiple is true.
5. Credentials and usage. The plan’s base username and password come from Get the credentials; Reset the credentials issues a new password and invalidates the old one at once. Requests and traffic over a window, as a daily series, come from Get a plan’s usage. Buying and topping up is Buy traffic, with an Idempotency-Key per order.
Troubleshooting
| Symptom | Check |
|---|---|
407 Proxy Authentication Required: | The password, or a typo in the username. The username must start with network-residential, and the credentials must belong to a residential plan; mobile credentials are refused here |
The IP changes on every request although you set session: | The same session id must be sent on every request; the id is case-sensitive |
| No IP for a small city: | Widen to region or drop city; asn and city cannot be combined |
| Connection refused on port 25 or another port: | See Limits and restrictions; some ports are blocked by default |
| A target answers 403: | The target may be on the restricted list; see Limits and restrictions |
| Another status from the gateway: | See Status codes |