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

  1. Open API in the dashboard sidebar.

  2. Press Create key. A name is optional; it helps when you run several scripts and want to tell their keys apart.

  3. 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/v1

Every 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/v1

Calls

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:

POST/proxies/pp123456/start

Get 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}'

Guides

Setting up a tool or device

The sidebar lists every guide. A few good starting points:

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.