Short answers
How do I use a proxy with curl?
Pass the proxy URL with -x or its long form --proxy, for example -x "http://gw.portproof.org:7000", and the proxy username with --proxy-user (short form -U). Without a scheme curl treats the value as an HTTP proxy. Use socks5h:// for a SOCKS5 proxy that should resolve hostnames itself.
How do I make curl skip the proxy?
Use --noproxy '*' to skip every proxy for one command, or --noproxy with a comma-separated host list to skip only those hosts. -x "" also disables a proxy set in the environment. Both override the proxy environment variables for that run only.
How do I check if my proxy is working?
Send one request through it to an endpoint that reports the address it sees, with curl -x for the proxy. For an interactive check, give --proxy-user the full username only and enter the password at the prompt. Confirm the expected response status and body; an error response is not a successful destination check. Record the curl error separately from any HTTP status.
How do I see which country my proxy exits from?
Ask a service that echoes the address it sees; ours answers on the echo endpoint printed in the setup docs. It returns the exit IP, not a country: look that address up in the geolocation database your target site uses, when that source is available. A database classification may still differ from the location the website reports. The API connection test makes a separate request from our side. It returns exit_country only for an observed classification, with country_verified true. Otherwise exit_country is null and country_verified is false. This is not proof of a physical location.
How do I test a SOCKS5 proxy with curl?
Use the same -x flag with a socks5h:// URL and port 7001 instead of http:// and port 7000. The h in socks5h tells curl to resolve the hostname at the proxy rather than locally, so choose it when name resolution should happen at the proxy. Local and remote DNS can return different destination addresses.
Why does curl succeed while my browser fails?
The browser can use different proxy settings, credentials or exclusions. In Playwright, configure the server, username and password in the browser proxy options, then test a page navigation. The client settings guide covers the comparison.
How do I confirm that rotation actually changed the IP?
Compare the reported address across a few permitted connections using the same configuration. Two rotating connections can use the same public address. A repeated address alone does not prove rotation failed, and an IP comparison does not identify the underlying device.
Does testing use my GB?
Yes. Traffic sent through the gateway uses the account balance, including the diagnostic request and response. Keep tests small and bounded. The account meter refreshes periodically, so it may not change immediately after a test.
How do I measure proxy latency?
Use curl’s time_connect, time_starttransfer and time_total fields. time_connect ends when TCP reaches the host or proxy; time_starttransfer ends at the first response byte. Their difference includes several stages, not just destination processing.
Calling cURL from PHP? Use the PHP cURL guide for the extension’s options, CONNECT status and a prompted-password example. Shell flags below are not PHP option names.
The one-line check
The proxy address goes in -x, the full username goes in --proxy-user without a colon or password, and the destination is an endpoint that reports the address it sees. In an interactive terminal, curl asks for the password. Enter it at that prompt; each curl invocation asks again. Keeping the password out of the URL also avoids mixing credential text with URL syntax. The 407 guide covers authentication failures. curl interactive authentication.
USERNAME stands for the account part of your username; both it and the password are in the dashboard and in GET /v1/traffic.
# Replace USERNAME with the account part shown in the dashboard.
# Enter the password at each curl prompt; leave it out of the command.
curl --disable --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -x "http://gw.portproof.org:7000" \
--proxy-user "USERNAME-mbl-us-rot-auto10" \
https://api.portproof.org/v1/echo-ip
# record tunnel and destination statuses separately
curl --disable --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -o /dev/null -w 'connect=%{http_connect} target=%{response_code}\n' \
-x "http://gw.portproof.org:7000" \
--proxy-user "USERNAME-mbl-us-rot-auto10" \
https://api.portproof.org/v1/echo-ipRead the tunnel and destination results
The body check and status check above are separate requests. They can use different rotating exits. For the shown HTTP proxy and HTTPS destination, connect records the proxy’s CONNECT response; target records the destination HTTP response. Interpret them together with curl’s error and the expected body.
| Printed result | What it establishes | Next check |
|---|---|---|
connect=200 target=200 | The tunnel opened and a destination HTTP response arrived. | Check the expected body, then repeat the small check in your actual client. This does not prove country or workload success. |
connect=200 target=403 | The tunnel opened; the destination returned a refusal. | Follow the endpoint’s permitted access rules. A destination refusal does not by itself identify a proxy-password problem. |
connect=200 target=429 | The tunnel opened; the destination HTTP response reports a request limit. | Read its retry instructions and plan a bounded recovery. |
connect=407 target=000 | The proxy refused authentication; no destination HTTP status was recorded. | Check the supplied credentials and follow the 407 guide. |
connect=000 target=000 | Neither a CONNECT response nor a destination HTTP status was recorded. | Read curl’s error first: DNS, connection and timeout failures need different checks. Use connection troubleshooting. |
000 means no recorded HTTP status; it is not a server status code or a diagnosis. A tunnel result of 200 with target=000 can still precede a TLS or transfer failure. The CONNECT guide separates those stages. For a certificate-verification error after the tunnel opens, use the proxy certificate checks. SOCKS5 and plain HTTP requests need their own interpretation; this table is scoped to the shown HTTPS tunnel.
curl can exit with code 0 after receiving HTTP 403 when --fail is absent, as in these examples. A completed transfer is separate from an acceptable HTTP response. In a POSIX-style shell, run printf 'curl exit=%s\n' "$?" immediately after curl to read its exit code; another command replaces that value. See the curl write-out reference.
curl proxy options: -x, --proxy and --proxy-user
-x and --proxy are the same option. Its value is a proxy URL: the scheme selects the proxy protocol, then the host and port. Write the port every time; when it is missing, curl assumes 1080, which is rarely the HTTP port you meant. On this gateway HTTP is on port 7000 and SOCKS5 on port 7001.
| Option or scheme | What it does | Note |
|---|---|---|
-x URL, --proxy URL | Send the transfer through that proxy | Overrides any proxy environment variable for this command |
--proxy-user USER, -U USER | Authenticate to the proxy | With a username and no colon, curl prompts for the password |
http:// | HTTP proxy; HTTPS destinations go through CONNECT | Also the assumption when the value has no scheme |
https:// | HTTP proxy reached over TLS | Only when the proxy itself offers TLS; not needed for HTTPS websites |
socks5:// | SOCKS5 proxy, hostname resolved locally | Your local DNS chooses the destination address |
socks5h:// | SOCKS5 proxy, hostname resolved by the proxy | Same as --socks5-hostname; the usual choice for a remote exit |
--proxy-anyauth | Let curl pick the proxy authentication method | Basic is the default; most gateways need no change |
Credentials can also sit inside the URL as http://USER:PASS@host:port. Characters such as @, : and / in a password then need percent-encoding, and the password lands in your shell history. The proxy format guide shows the encoding; --proxy-user with a prompt avoids both problems.
Proxy environment variables curl reads
| Variable | Applies to | Detail |
|---|---|---|
http_proxy | http:// URLs | Lower case only: curl ignores HTTP_PROXY to protect CGI environments |
https_proxy or HTTPS_PROXY | https:// URLs | Either spelling |
ALL_PROXY or all_proxy | Any protocol without its own variable | Can hold a socks5h:// URL |
NO_PROXY or no_proxy | Hosts that should connect directly | Comma-separated names or addresses; * matches every host |
Keep the password out of these variables; curl prompts when the URL carries a username only. Unset them when you finish, or every later curl call in that shell uses the gateway.
export https_proxy="http://gw.portproof.org:7000"
export http_proxy="http://gw.portproof.org:7000"
export NO_PROXY="localhost,127.0.0.1"
curl --silent --show-error --max-time 15 \
--proxy-user "USERNAME-peer-nl-rot-ondemand" \
https://api.portproof.org/v1/echo-ip
unset https_proxy http_proxy NO_PROXYThe examples elsewhere on this page start with --disable so a .curlrc file cannot add its own proxy, and pass --noproxy '' so an inherited NO_PROXY cannot send the request around the gateway. Other programs read these variables differently: the environment variable guide compares them and explains NO_PROXY matching.
Skip the proxy: --noproxy and NO_PROXY
# no proxy at all for this command, whatever the environment says
curl --noproxy '*' https://example.com/
# proxy everything except these hosts
curl -x "http://gw.portproof.org:7000" --proxy-user "USERNAME-peer-nl-rot-ondemand" \
--noproxy 'localhost,internal.example' https://example.com/
# an empty proxy also disables an environment proxy
curl -x "" https://example.com/--noproxy replaces the NO_PROXY list for that command. A name in the list also matches its subdomains, and an entry is a hostname or address, not a URL. Use it to keep local services and your own infrastructure off the gateway, where they would only use traffic.
Debug a curl proxy connection with -v
-v prints each stage: which proxy curl connected to, the CONNECT request it sent and the status line the proxy returned, then the TLS handshake with the destination. Verbose output also prints the Proxy-Authorization header, which carries your username and password in Base64. Filter it out before the output reaches a terminal recording, a log or a support message.
The filter keeps curl’s info lines, the CONNECT request line and the status lines. The password prompt passes through the same filter, so curl waits without showing it: type the password and press Enter. Read the first status line after CONNECT: 200 means the tunnel opened; 407 means the gateway refused the credentials.
curl --disable -v --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -o /dev/null \
-x "http://gw.portproof.org:7000" --proxy-user "USERNAME-peer-nl-rot-ondemand" \
https://api.portproof.org/v1/echo-ip 2>&1 | grep -E '^(\* |> CONNECT|< HTTP)'A status line from the proxy and a status line from the destination can both appear; the first belongs to the tunnel. --trace-ascii FILE records even more, including every header, so treat that file as a secret. The CONNECT guide reads a failed tunnel stage by stage.
Exit address and round trip
The echo endpoint reports the exit IP it received. It does not confirm the exit country; a geolocation lookup is a separate observation and different services can classify the same address differently. time_connect measures time until the TCP connection to the host or proxy is complete. time_starttransfer measures time until the first response byte. Their difference includes more than destination processing, so it is not a direct measure of the target site’s work.
Keep the endpoint, client and settings consistent when comparing timings. Record several bounded checks; one result is only one observation.
curl --disable --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -o /dev/null \
-w 'connect %{time_connect}s first byte %{time_starttransfer}s total %{time_total}s\n' \
-x "http://gw.portproof.org:7000" \
--proxy-user "USERNAME-peer-gb-rot-auto10" \
https://api.portproof.org/v1/echo-ipThe API can also run the check from our side: POST /v1/traffic/test connects with a pool, a country and a rotation mode and reports whether it worked, the exit IP and the latency. It is limited to six calls a minute. Read country_verified: only true marks an observed country classification in exit_country. Otherwise exit_country is null. The requested country is never returned as the exit, and an observed classification is not physical-location proof. This separate check does not prove where an earlier client request exited or how a website classifies it.
Observe per-connection rotation
Per-connection rotation selects a route for each new connection on a backconnect gateway. Two rotating connections can use the same public address, for example when carrier-grade NAT puts several devices behind one address; the CGNAT guide explains why. Compare the configuration and the result of several permitted checks; a repeated address alone does not prove rotation failed. The example addresses below are masked documentation-range values, not pool exits.
Example output only. Addresses in 203.0.113.0/24 and 198.51.100.0/24 are documentation ranges, not exits of the pool.
for i in 1 2; do
curl --disable --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -x "http://gw.portproof.org:7000" \
--proxy-user "USERNAME-peer-es-rot-ondemand" \
https://api.portproof.org/v1/echo-ip
echo
done
# example: the exits differ
# 203.0.113.x
# 198.51.100.xTimed mode requests rotation on the selected schedule. It does not promise a different public address at an exact instant or change every request on an already open connection. The rotation and duration guide explains the boundaries.
Observe a sticky session
U="USERNAME-mbl-gb-sid-check7-rot-sticky"
curl --disable --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -x "http://gw.portproof.org:7000" --proxy-user "$U" https://api.portproof.org/v1/echo-ip; echo
sleep 5
curl --disable --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -x "http://gw.portproof.org:7000" --proxy-user "$U" https://api.portproof.org/v1/echo-ip; echo
# example: both calls report the same exit
# 192.0.2.x
# 192.0.2.xThe same checks over SOCKS5
socks5h resolves the hostname at the gateway; plain socks5 resolves it locally using the client’s resolver.
curl --disable --silent --show-error --noproxy '' --connect-timeout 5 --max-time 15 -x "socks5h://gw.portproof.org:7001" \
--proxy-user "USERNAME-peer-nl-rot-ondemand" \
https://api.portproof.org/v1/echo-ipWhich protocol to prefer, and what SOCKS5 can carry that an HTTP proxy cannot, is in the HTTP or SOCKS5 guide.
What each failure message means
| What you see | Where it failed | Usual cause |
|---|---|---|
| HTTP 407 | at the gateway | Rejected account credentials or exhausted traffic. Read the gateway code; malformed username syntax is documented as 400 bad_username. |
| HTTP 400 with bad_username | at the gateway | Upper case, a hyphen inside a value, or an unknown token in the username. |
| HTTP 502 with no_exit_available | at the gateway | No device of that pool is online in that country right now. |
| Connection refused | before the gateway | Wrong port, or a local firewall. HTTP is 7000, SOCKS5 is 7001. |
| Operation timed out | connection or transfer | The configured deadline elapsed. Check the failing stage and endpoint before changing a timeout. |
| SSL certificate problem | at the destination | Your own trust store, or a network that intercepts TLS. The proxy tunnels TLS; it does not terminate it. |
| Empty reply from server | transfer | No HTTP response was received. Inspect the connection and server evidence before assigning a cause. |
For a refused connection, a timeout or a gateway name that does not resolve, follow connection refused and timeouts. For a failed tunnel, diagnose the CONNECT response separately from the destination status.
The same test in Python and Node
Once curl succeeds, repeat the check from the process that will run your job. The complete Python Requests setup covers encoded credentials, timeouts and SOCKS5; the Node.js fetch setup covers explicit dispatchers, deadlines and response cleanup. For a PowerShell script, use the PowerShell proxy guide to set the gateway and prompted credential on one request.
What a test costs
Proxy tests use traffic. The response body is only part of a transfer, so do not estimate the charge from its size alone. Keep the endpoint small, limit repeated checks and compare a representative run with the account usage meter after it refreshes.
The GB planning guide helps size a workload, and pricing shows the current order rates. Check locations for current mobile 4G/5G and residential availability. Both pools use the connection format described in the setup docs.
| Order size | Per GB | Saving |
|---|---|---|
| 1 to 4 GB | EUR 1.99 | |
| 5 to 24 GB | EUR 1.79−10 % | |
| 25 to 49 GB | EUR 1.49−25 % | |
| 50 to 99 GB | EUR 1.29−35 % | |
| 100 to 249 GB | EUR 1.09−45 % | |
| 250 GB and more | EUR 0.89−55 % |
GB never expire. What you buy stays on your balance until you use it; a new purchase adds to the same balance.
The per-GB ladder these tests draw on. One balance covers both pools.
What is not allowed
What is not allowed: test against your own endpoints or a public echo service, and use the result for lawful work such as price monitoring, ad verification, market research and QA. Probing infrastructure you do not own, credential stuffing and account farming are refused. See the acceptable-use policy.
Read next
HTTP 407 Proxy Authentication Required: fixes
Read the gateway code, check credentials and balance, then separate a rejected HTTPS tunnel from an HTTP response.
Read the guide
Sticky proxy sessions: rotation and duration
Choose a rotation mode, understand session lifetime and keep the configuration consistent through a job.
Read the guide
More in Connect and debug
- ERR_TUNNEL_CONNECTION_FAILED in Chrome and Edge
- Docker proxy: pull, build and container settings
- Proxy format: URL, list formats and ports
- Git proxy: git config http.proxy and checks
- HTTP 429: rate limits and careful retries
- Fix proxy certificate errors in curl
Show 26 more
- pip proxy setup and connection checks
- npm CLI proxy setup and connection checks
- PHP cURL proxy setup and authentication
- Python urllib proxy setup and authentication
- Firefox proxy settings and authentication
- PowerShell proxy setup and authentication
- Puppeteer proxy setup and authentication
- The proxy requires a username and password
- Proxy settings: what they mean and how to check
- Fix ERR_PROXY_CONNECTION_FAILED in Chrome
- Proxy errors: causes and fixes for each message
- Chrome proxy extension: FoxyProxy, ZeroOmega
- Proxy connection refused or timing out
- Wget proxy setup and authentication
- Postman proxy server setup and authentication
- Axios proxy setup for Node.js
- Go HTTP proxy setup with authentication
- Scrapy proxy setup with authentication
- aiohttp proxy setup with authentication
- HTTPX proxy setup for sync and async
- Python Requests proxy setup
- Playwright proxy setup and authentication
- Node.js fetch proxy setup with Undici
- SOCKS5 vs HTTP proxy: which to use
- Fix CONNECT tunnel failed: 403, 407, 502, 503
- HTTPS_PROXY not working? Check your client
Buy mobile and residential proxy GB
Choose your GB or reserve a mobile device.