# Residential endpoints & countries API
Source: https://proxuno.com/docs/api-residential
Updated: 2026-09-16

REST API

Reference for GET /residential/endpoints (country, city, rotating or sticky sessions, protocol, format, count) and GET /countries.

Updated 16 Sept 2026 2 min read API v1

Residential "endpoints" are ready-to-use proxy lines for the rotating residential gateway. Nothing is reserved when you generate them: each line is just the gateway address with a username carrying your targeting flags (see [Residential targeting](/docs/residential-targeting)). Generate as many as you need, as often as you need — traffic is billed only when it flows.

## Generate endpoints[#](#generate-endpoints)

HTTPCopy

```http
GET /residential/endpoints
```

| Parameter | Values | Default |
| --- | --- | --- |
| `country` | ISO code (`fr`, `gb`/`uk`, `de`…) or `eu` for anywhere in the pool | `eu` |
| `city` | city slug of that country (`lyon`, `the-hague`…). Not allowed with `eu`. | none |
| `session` | `rotating` (new IP per request) · `sticky` (one random session id per line) | `rotating` |
| `ttl` | 1–30 — session lifetime in minutes, used with `sticky` | `10` |
| `protocol` | `http` (port 7000) · `socks5` (port 7001) | `http` |
| `format` | `host_port_user_pass` · `user_pass_at_host_port` · `user_pass_host_port` · `url` · `curl` · `json` | `host_port_user_pass` |
| `count` | 1–1000 | `10` |

Line formats are described in [Export formats](/docs/export-formats); `curl` returns a ready-to-run test command per line, and `json` returns objects instead of strings.

cURLPythonNode.js

Copy

```bash
curl -s "https://proxuno.com/api/v1/residential/endpoints?country=fr&city=paris&session=sticky&ttl=15&count=3&format=url" \
-H "Authorization: Bearer $PROXUNO_API_KEY"
```

```python
import os, httpx

api = httpx.Client(base_url="https://proxuno.com/api/v1", headers={"Authorization": f"Bearer {os.environ['PROXUNO_API_KEY']}"}, timeout=30)
lines = api.get("/residential/endpoints", params={
"country": "fr", "city": "paris", "session": "sticky", "ttl": 15, "count": 3, "format": "url",
}).json()["data"]
```

```javascript
const qs = new URLSearchParams({ country: "fr", city: "paris", session: "sticky", ttl: "15", count: "3", format: "url" });
const res = await fetch(`https://proxuno.com/api/v1/residential/endpoints?${qs}`, {
headers: { Authorization: `Bearer ${process.env.PROXUNO_API_KEY}` },
});
const { data: lines } = await res.json();
```

Response:

JSONCopy

```json
{
"data": [
"http://px4k2m9q7a-country-fr-city-paris-session-q8z1m4ka-ttl-15:Rb8Tn3Wq6Ys1Kd5P@resi.gw.proxuno.com:7000",
"http://px4k2m9q7a-country-fr-city-paris-session-c3v7n0xd-ttl-15:Rb8Tn3Wq6Ys1Kd5P@resi.gw.proxuno.com:7000",
"http://px4k2m9q7a-country-fr-city-paris-session-h6t2w9rb-ttl-15:Rb8Tn3Wq6Ys1Kd5P@resi.gw.proxuno.com:7000"
],
"meta": {
"host": "resi.gw.proxuno.com",
"port": 7000,
"protocol": "http",
"country": "fr",
"city": "paris",
"session": "sticky",
"ttl": 15,
"format": "url",
"count": 3,
"bytes_remaining": 14820000000
}
}
```

With `format=json`, each entry is an object:

JSONCopy

```json
{ "host": "resi.gw.proxuno.com", "port": 7000, "username": "px4k2m9q7a-country-fr-city-paris", "password": "Rb8Tn3Wq6Ys1Kd5P", "protocol": "http" }
```

Notes:

- The lines contain your residential password. Keep generated lists out of logs and shared storage.
- In `rotating` mode all lines are identical — each request through any of them gets a new IP. Tools that require "a list of proxies" are happy with that.
- `meta.bytes_remaining` is your residential balance across active packages. Generation works with 0 bytes left, but connections will be refused until you top up traffic.
- An unknown country or city returns `400 validation_error` with `error.fields.country` or `error.fields.city`.

## List countries and cities[#](#list-countries-and-cities)

HTTPCopy

```http
GET /countries
```

Returns every country of the network with product availability, cities (residential targeting) and carriers (mobile):

JSONCopy

```json
{
"data": [
{
"code": "nl",
"name": "Netherlands",
"slug": "netherlands",
"mobile": true,
"static": true,
"residential": true,
"carriers": [
{ "slug": "kpn", "name": "KPN", "tech": ["4G", "5G"] },
{ "slug": "odido", "name": "Odido", "tech": ["4G", "5G"] },
{ "slug": "vodafone-nl", "name": "Vodafone NL", "tech": ["4G"] }
],
"cities": [
{ "slug": "amsterdam", "name": "Amsterdam" },
{ "slug": "rotterdam", "name": "Rotterdam" }
],
"pool_size": 540000,
"mobile_from_cents": 900
}
],
"meta": { "total": 20, "eu_code": "eu" }
}
```

- `name` is the English name; display localised names in your own UI from the ISO code.
- `carriers` is empty for residential-only countries.
- `mobile_from_cents` is the price of the cheapest mobile plan in that country (24 hours), `null` without mobile proxies.
- `pool_size` is an indicative count of residential IPs available in that country.

Cache this response for a day: the list changes only when a country or carrier is added, which is announced in the [changelog](/changelog).

Something unclear, outdated or wrong on this page? Tell us — documentation issues are fixed in the next release at the latest.

[Report an issue with this page](/contact?topic=support&subject=Documentation%20issue%3A%20Residential%20endpoints%20%26%20countries%20API)