Proxies
Help center

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.

RegionHost
Europegw-eu.datafuel.ai
United Statesgw-us.datafuel.ai
Asiagw-as.datafuel.ai

Ports

PortProtocolsUse it for
5555HTTP, HTTPS, SOCKS5 over TCP and UDPThe default. Works for everything, including SOCKS5 UDP
7777HTTP, HTTPSClients that only speak HTTP proxies
1080SOCKS5 over TCP onlyClients 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.

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

Text
network-residential-country-gb-region-england-city-london-session-39yrj3-ttl-60
└── pool ─────────┘└───────── where the IP comes from ─────────┘└── how long you keep it ──┘
PoolUsername starts with
Residential, desktop devicesnetwork-residential
Residential, UDP-verified IPsnetwork-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.

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

Shell
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

Shell
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

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

Shell
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

Shell
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

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

Shell
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

PYTHON
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

JAVASCRIPT
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

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

Shell
curl https://api.datafuel.ai/api/v1/residential/plans \
     --header "Authorization: Bearer $API_KEY"
JSON
{
  "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.

Shell
curl https://api.datafuel.ai/api/v1/residential/plans/$PLAN \
     --header "Authorization: Bearer $API_KEY"
JSON
{
  "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.

Shell
curl "https://api.datafuel.ai/api/v1/residential/plans/$PLAN/locations?country=US&search=los" \
     --header "Authorization: Bearer $API_KEY"
JSON
{
  "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.

Shell
curl "https://api.datafuel.ai/api/v1/residential/plans/$PLAN/asns?search=comcast" \
     --header "Authorization: Bearer $API_KEY"
JSON
{
  "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.

Shell
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"
     }'
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

SymptomCheck
407 Proxy Authentication RequiredThe 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 sessionThe same session id must be sent on every request; the id is case-sensitive
No IP for a small cityWiden to region or drop city; asn and city cannot be combined
Connection refused on port 25 or another portSee Limits and restrictions; some ports are blocked by default
A target answers 403The target may be on the restricted list; see Limits and restrictions
Another status from the gatewaySee Status codes