Proxies

Pass a proxy URL as proxy. The TLS handshake still happens between the native client and the target site, through the proxy's tunnel, so the fingerprint is the same as without a proxy.

// Every request of this session goes through the proxy.
const session = new Session({
  proxy: "http://user:pass@proxy.example.com:8080",
});
await session.get("https://httpbin.org/ip");

URL formatCopy Anchor Link

http://host:port
http://user:pass@host:port
socks5://user:pass@host:port

URL-encode special characters in the username or password (encodeURIComponent).

const socks = new Session({
  proxy: "socks5://user:pass@proxy.example.com:1080",
});

A different proxy for one requestCopy Anchor Link

proxy in the request options overrides the session's proxy for that request:

// A different proxy for one request. The next request goes back to the
// session's proxy (or none).
await session.get("https://httpbin.org/ip", {
  proxy: "http://user:pass@other-proxy.example.com:8080",
});

The session switches its native client to the request's proxy and back again on the next request without one. Each switch drops the pooled connections. If you alternate proxies on every request, use one session per proxy instead.

Rotating proxiesCopy Anchor Link

Some providers give each connection a new exit IP. Set isRotatingProxy: true so the session re-applies the proxy before every request, instead of sending later requests over an existing connection (and so the same IP):

// The provider hands out a new exit IP per connection: re-apply the proxy
// before every request instead of reusing pooled connections.
const rotating = new Session({
  proxy: "http://user:pass@rotating.example.com:8000",
  isRotatingProxy: true,
});

It can be set on the session or per request.

CONNECT headersCopy Anchor Link

For HTTP proxies, connectHeaders adds headers to the CONNECT request that opens the tunnel. Some providers read session or country settings from them:

const session = new Session({
  proxy: "http://proxy.example.com:8080",
  connectHeaders: { "Proxy-Session": ["abc123"] },
});

Values are arrays of strings. A request's connectHeaders replace the session's.

Checking the exit IPCopy Anchor Link

Request https://httpbin.org/ip through the session; the reply shows the IP the target sees.