ports.io documentation

Connect your application to residential proxies. Learn how to authenticate, choose a location, keep a session, and understand your usage.

Make your first request

Create a proxy key as a workspace owner or admin, obtain your assigned HTTP or SOCKS5 proxy URL, and send a request through v1_rotate.

curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate:$PORTS_PROXY_KEY" \
  --connect-timeout 10 --max-time 30 \
  https://example.com

Set PORTS_PROXY_URL to your assigned proxy URL, including its scheme, hostname, and port. Set PORTS_PROXY_KEY to the complete secret shown when you create a key.

For SOCKS5 with curl or Python Requests, use socks5h:// so the destination hostname reaches the proxy for the exit to resolve. Their socks5:// mode sends a locally resolved IP address, which is refused. Use a destination hostname and the assigned SOCKS port; an HTTPS proxy’s TLS-only port cannot be reused just by changing the URL scheme. HTTP proxies use the assigned http:// or https:// URL. See Protocols and limits for transport details.

Connect your application

QuickstartMake your first request with an HTTP proxy or SOCKS5 with remote DNS.

curlConfigure HTTP or socks5h proxies and inspect failures with curl.

PythonUse Requests with HTTP proxies or socks5h for remote DNS.

JavaScriptUse Undici for HTTP proxies or SOCKS5 with destination DNS at the proxy.

Routing reference

AuthenticationAuthenticate HTTP or SOCKS5 with a routing username and your key as the password.

Username formatThe complete grammar, its clauses, and the validation rules.

Geographic targetingFilter exits by country or by region.

Sessions and rotationRotate exits, or keep related connections on one.

Account and operations

Manage proxy keysCreate, rename, replace, and revoke keys.

Usage measurementWhat the console's traffic counters include.

Protocols and limitsHTTP and SOCKS5 support, remote DNS, size limits, and deadlines.

TroubleshootingDiagnose HTTP proxy errors and SOCKS5 handshake or tunnel failures.

Use these docs with AI tools

Every page is also published as Markdown at its address with .md in place of the final slash. Start an assistant from llms.txt, an index of every page, or give it llms-full.txt for everything in one file. The AI tools guide shows how to set up Claude Code, Codex and Cursor. Never include actual proxy secrets in prompts.