ProxyShard API Examples

Practical Python recipes for the ProxyShard user API.

These are the answers we send to questions like:

"How do I request 5 residential proxies in country X with the API?"

API reference · Website · Issues

---

What's inside

Script	Purpose
01_check_account.py	Verify your token works (GET /user/api/me)
02_list_residential_subusers.py	List residential sub-users and their bandwidth
03_browse_residential_locations.py	Countries, regions and cities for targeting
04_generate_residential_proxies.py	Main recipe — generate N proxies with targeting
05_test_residential_proxy.py	Health-check a generated proxy through ipapi.co
06_resolve_relay_ipv4.py	Get a current IPv4 for the relay (instead of domain)
07_list_dc_isp_active_proxies.py	Datacenter / ISP — list active proxies for an order
08_check_order_status.py	Datacenter / ISP — order status, expiration, add-ons (p0f slots)
09_test_dc_isp_proxy.py	Datacenter / ISP — health-check every proxy on an order

Shared logic lives in proxyshard.py: a small ProxyshardClient and the residential username builder.

---

How residential proxy URLs work

The API does not have a "generate proxy" endpoint. This trips up most new users. The proxy URL is composed client-side. Format:

scheme://USERNAME:PASSWORD@HOST:PORT

Real example:

http://plan-premium-country-de-region-berlin-sid-abc12345:eu5ymcyjcxmxsmc9@relay-eu.proxyshard.com:8080

Which decomposes as:

Part	Example value	Source
scheme	http (port 8080) or socks5 (port 1080)
USERNAME — targeting	plan-premium-country-de-region-berlin-sid-abc12345	Built client-side, see below
PASSWORD	eu5ymcyjcxmxsmc9	The sub-user's proxy_password from /user/api/proxies/sub-users
HOST	relay-eu.proxyshard.com	One of relay-eu / relay-ua / relay-ru — pick the one geographically closest
PORT	8080 (HTTP) or 1080 (SOCKS5)

USERNAME segments:

Segment	Required	Notes
plan-<type>	yes	plan-premium for Premium Residential, plan-limited for Standart Residential
country-<code>	yes	ISO 2-letter code from /user/api/proxies/countries (e.g. de). Use any for random
region-<code>	optional	From /user/api/proxies/regions
city-<code>	optional	From /user/api/proxies/cities
sid-<random>	optional	Sticky-session id. Same sid → same exit IP. New sid → new IP
ttl-<seconds>	optional	Sticky-session lifetime in seconds

proxyshard.py::build_residential_username() handles the composition. Each example uses it.

---

Datacenter and ISP proxies

These work differently from residential. The dashboard provisions concrete dedicated IPs at purchase time, and you fetch them with GET /user/api/proxies/active?order_id=.... No client-side URL building required.

Workflow:

1. 08_check_order_status.py — list active orders, pick a Datacenter or ISP order id.
2. Put it in .env as PROXYSHARD_ORDER_ID=....
3. 07_list_dc_isp_active_proxies.py — get the proxy strings.
4. 09_test_dc_isp_proxy.py — verify each proxy reaches the internet and reports the expected country.

If a DC/ISP proxy fails, the upstream target has likely blocked the IP, or the proxy is in maintenance. Try another IP on the same order; if you hit issues, reach us on live chat and we'll help.

---

Getting your API token

1. Sign in at dashboard.proxyshard.com.
2. Click the avatar selector in the bottom-left (1), open Settings (2).
3. In the top tabs choose API (3), then Copy the token (4) or Change API Key to rotate it.

Direct link: https://dashboard.proxyshard.com/en/profile?tab=api-key

The token is a JWT-style string starting with eyJ.... Put it in a local .env:

cp .env.example .env
# edit .env and paste the token

PROXYSHARD_TOKEN is also accepted as a plain environment variable if you don't want to use a file.

Tokens carry full account access. Treat them like a password — never commit them to version control. The included .gitignore excludes .env.

---

Setup

git clone https://github.com/ProxyShard/proxyshard-api-examples.git
cd proxyshard-api-examples

python -m venv .venv
. .venv/bin/activate         # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env
# paste your PROXYSHARD_TOKEN into .env

python 01_check_account.py

If 01_check_account.py prints your email and balance, the token works. Move on to the other examples.

Python 3.9+ is supported.

---

Common patterns

Sticky session vs rotating IP

# Same sid → same exit IP across requests
build_residential_username("premium", country="de", sid="my-stable-session")

# Rotating: new IP every request
build_residential_username("premium", country="de", sticky=False)

Sticky session lifetime: the maximum sticky lifetime is 1 day. The session can end earlier — residential exit IPs are real home devices, and if the device leaves the pool (powers off, switches network, user revokes), the IP changes and you get a fresh one on the next request. Treat sticky as best-effort, not guaranteed.

Random country (load balance across the whole pool)

build_residential_username("premium", country="any")

IP literal instead of domain

If your environment can't resolve DNS (or you want to skip lookup time on every request), resolve once and use the IP:

import socket
ip = socket.gethostbyname("relay-eu.proxyshard.com")
proxy_url = f"http://{username}:{password}@{ip}:8080"

⚠️ Relay IPs change. Re-resolve at least once per hour, or on connection errors. Don't hard-code IPs into permanent config. See 06_resolve_relay_ipv4.py.

Plug into requests

proxies = {"http": proxy_url, "https": proxy_url}
requests.get("https://api.ipify.org?format=json", proxies=proxies, timeout=15)

SOCKS5 with requests

pip install "requests[socks]"

proxy_url = build_proxy_url(username, password, scheme="socks5")  # uses port 1080

---

If residential proxies aren't working

If 05_test_residential_proxy.py fails or you get connection errors / wrong-country results:

1. Stale sticky session. The exit device left the network. Generate a new sid (drop the old one) and retry — the relay will route through a different device.
2. Bandwidth exhausted. Check the sub-user with 02_list_residential_subusers.py — if data_spent is at or near data, top up the sub-user's traffic from the dashboard or via API.
3. Targeting too narrow. This is rarely a country issue; more often it's a region, and most often a small city, that has too few IPs available right now. Drop city or region from the username, or pick a neighbouring location. For small cities, Premium Residential generally has better coverage than Standart — if you need a specific city, go premium.
4. Still stuck? Reach us on live chat and we'll help you figure it out.

---

Links

• API reference: https://docs.proxyshard.com/polzovatelskoe-api/general
• Residential API: https://docs.proxyshard.com/polzovatelskoe-api/residential-proxies
• Datacenter & ISP API: https://docs.proxyshard.com/polzovatelskoe-api/datacenter-and-isp-proxies
• Models: https://docs.proxyshard.com/polzovatelskoe-api/models
• Business inquiries: business@proxyshard.com

---

License

MIT