ProxyGuys API: quickstart and guides
Most of what you do by hand in My Proxies can also run from a script: reading a proxy's connection details, getting a fresh IP, moving it to another US city, scheduling rotation, and editing the IP whitelist. Requests and replies are JSON over HTTPS, and one key covers the whole account. Below is the shortest path from no key to a working call, followed by the setup guides for browsers, devices and code.
You can use a proxy without the API
Every proxy in My Proxies has two Connection boxes, and their copy buttons hand you a complete URL: http://USERNAME:PASSWORD@HOST:HTTP_PORT for HTTP and socks5h://USERNAME:PASSWORD@HOST:SOCKS5_PORT for SOCKS5. Scripts and tools that take a proxy URL accept either one as it is; browsers and device settings usually want the host, port, username and password in separate fields, and the guides at the bottom of this page show where each goes. A proxy you just paid for reads Pending · starts on activation: press Start proxy first, because changing its IP or location only works once its time has begun.
Step 1
Create an API key
Open API in the dashboard sidebar.
Press Create key. A name is optional; it helps when you run several scripts and want to tell their keys apart.
Copy the key right away. It is displayed this one time only, so put it in a password manager or an environment variable before you leave the page.
Whoever holds the key can manage your proxies through the API, so guard it like a password. If one leaks, press Revoke next to it on the same page and create a new one; scripts still sending the old key start getting 401.
Step 2
Base URL and authentication
https://proxyguys.com/api/v1Every path below hangs off that address. Send the key in a header on each request: Authorization: Bearer YOUR_API_KEY. For a plain GET you open from a bookmark, adding ?key=YOUR_API_KEY to the URL also works, though the key then sits in browser history and server logs, so stick to the header in code.
When something goes wrong the reply is JSON with an error field; a missing or unknown key gives 401. Calling the base URL with no key at all returns the list of endpoints, which is a handy first test.
# Store the key once per shell session (never commit it to a repo)
export PROXYGUYS_API_KEY="YOUR_API_KEY"
# No key needed for this one: it lists every endpoint as JSON
curl -s https://proxyguys.com/api/v1Calls
List your proxies
GET /proxies returns every proxy on the account. Each one has an API id shaped like pp123456, which is what goes into the URLs below; it is not the proxy's username. Each entry also carries a connection block with host, http_port, socks5_port and username. For the password and ready-to-paste URLs, ask /credentials. Its SOCKS5 URL starts with socks5://; swap that for socks5h:// if you want hostnames resolved on the proxy side rather than on your machine.
# Every proxy on the account
curl -s https://proxyguys.com/api/v1/proxies \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"
# A single proxy; probe=true also test-dials it
curl -s "https://proxyguys.com/api/v1/proxies/pp123456?probe=true" \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"
# Host, ports, username, password and ready-made proxy URLs
curl -s https://proxyguys.com/api/v1/proxies/pp123456/credentials \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"A paused proxy can be started from code as well:
/proxies/pp123456/startGet a new IP
POST /proxies/{id}/rotate asks for a new IP, the scripted counterpart of the Change IP button. The call holds until the swap is finished (from the dashboard a change usually takes 30 to 90 seconds), so give your HTTP client a timeout longer than that. The reply includes new_ip, which can come back as null. You get one change per 60 seconds; a second request inside that window is refused with 409, code: "cooldown" and a retry_after telling you how many seconds remain.
curl -s -X POST https://proxyguys.com/api/v1/proxies/pp123456/rotate \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"
# The reply arrives once the change is finished and carries new_ip (it can be null).
# Asked again inside 60 seconds? HTTP 409, "code": "cooldown", and retry_after in seconds.Find a city and move there
GET /locations lists the US cities on the network with their location_id and how much free capacity each has; add ?available_only=1 to hide the full ones. Then send POST /proxies/{id}/relocate with one of three bodies: a location_id from that list, a city and state such as {"city": "Dallas", "state": "TX"}, or {"random": true} to land somewhere at random.
Moves need a pause of roughly three minutes between them. Asking sooner returns 409 with too_soon and retry_after. Bear in mind that IP lookup sites rely on their own databases, so a mobile IP may show up under a different city or state than the one you chose; that is normal on carrier networks and does not mean the move failed.
# US cities with free capacity, each carrying a location_id
curl -s "https://proxyguys.com/api/v1/locations?available_only=1" \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"
# Move the proxy to the one you picked
curl -s -X POST https://proxyguys.com/api/v1/proxies/pp123456/relocate \
-H "Authorization: Bearer $PROXYGUYS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"location_id": "LOCATION_ID"}'Rotate on a timer
PUT /proxies/{id}/rotation-schedule sets the same automatic rotation you find in the Rotation column. interval_minutes takes 5, 10, 30 or 60, and mode picks what changes each time:
same_city: a new IP in the same city on the same carrier (the dashboard's IP rotation, "Same city & carrier").full_pool: a random city anywhere in the pool (Location rotation, "Random across full pool").same_carrier: a random city, carrier unchanged (Location · keep carrier, "Random city, same carrier").
A proxy runs one schedule at a time. The first change lands one interval after you save, and the schedule keeps going whether or not anything is open on your side. DELETE on the same path switches it off.
# A new IP every 10 minutes, same city and carrier
curl -s -X PUT https://proxyguys.com/api/v1/proxies/pp123456/rotation-schedule \
-H "Authorization: Bearer $PROXYGUYS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"interval_minutes": 10, "mode": "same_city"}'
# Stop automatic rotation
curl -s -X DELETE https://proxyguys.com/api/v1/proxies/pp123456/rotation-schedule \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"Set the IP whitelist
PUT /proxies/{id}/ip-auth turns IP authentication on for up to 15 IPv4 addresses. The list you send replaces whatever was there, and protocol chooses whether the whitelist port speaks HTTP or SOCKS5 (each proxy has one whitelist port). Machines on the list connect to that port with no username or password; you can see and copy it in the dashboard under IP whitelist with Copy endpoint. Your normal ports keep accepting the username and password at the same time. Send {"enabled": false} to switch it off. On a few servers the whitelist is not offered, and the dashboard window says so.
# Let one server use the whitelist port with no username or password
curl -s -X PUT https://proxyguys.com/api/v1/proxies/pp123456/ip-auth \
-H "Authorization: Bearer $PROXYGUYS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true, "protocol": "http", "allowed_ips": ["203.0.113.10"]}'
# Switch IP authentication off
curl -s -X PUT https://proxyguys.com/api/v1/proxies/pp123456/ip-auth \
-H "Authorization: Bearer $PROXYGUYS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'Change the IP with a link, no key required
Every proxy has a change-IP link. Opening it, from a browser, curl, a phone shortcut or a scheduler, starts an IP change with no login and no API key. It answers in plain text with OK — rotating your IP now. Allow up to ~90 seconds for the new IP. and the usual limit of one change per 60 seconds applies. Since anyone holding the link can use it, keep it as private as a password.
You can copy it from the proxy's ⋮ menu (Copy change-IP link), from the Rotate URLs card on the API page, or with GET /proxies/{id}/rotate-links. Adding /random to the end gives the random-location link, which moves the proxy to a random city with a new IP; ?excluded_carriers=att,tmobile leaves out the carriers you list. If a link gets out, New change-IP link in the menu, New URLs on the API page or POST on rotate-links issues a replacement and the old one stops working.
# Look the links up once (this call needs the key)
curl -s https://proxyguys.com/api/v1/proxies/pp123456/rotate-links \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"
# From then on, no key at all: opening the link starts an IP change
curl -s "YOUR_CHANGE_IP_LINK"
# Random city with a new IP, skipping AT&T and T-Mobile
curl -s "YOUR_CHANGE_IP_LINK/random?excluded_carriers=att,tmobile"
# Link exposed somewhere? Issue fresh links; the old ones stop working
curl -s -X POST https://proxyguys.com/api/v1/proxies/pp123456/rotate-links \
-H "Authorization: Bearer $PROXYGUYS_API_KEY"Guides
Setting up a tool or device
The sidebar lists every guide. A few good starting points:
- Python requests: HTTP and SOCKS5 from a script
- Scrapy: a proxy for a whole crawl
- Playwright: a headless browser behind the proxy
- Rotating IPs: button, link, schedule or API
- IP whitelisting: connect without a password
- AdsPower: one proxy per browser profile
- Multilogin: profile proxy settings
- iPhone and iPad: Wi-Fi proxy settings
- Android: phones and tablets
- Paying with crypto: USDT, TRX, Bitcoin and Litecoin
A few calls are left out of this page: renewing a proxy (POST /proxies/{id}/renew with a tier of week or month), reading your balance (GET /balance) and setting a new proxy password (PUT /proxies/{id}/password). For those, see the full API reference. Stuck? Open a ticket from Tickets in the dashboard or write to support@proxyguys.com.