Proxy guide

How to Rotate Proxies in Node.js

The Proxy11 Node.js SDK returns an ip:port candidate. This example passes that address to HttpsProxyAgent so Node's HTTPS client actually routes the request through it.

SDKs

Example

npm install proxy11 https-proxy-agent
const https = require("node:https");
const { HttpsProxyAgent } = require("https-proxy-agent");
const { ProxyClient } = require("proxy11");

const client = new ProxyClient(process.env.PROXY11_API_KEY);
const rotator = client.rotator({
  country: "us",
  proxyType: "anonymous",
  autoRefresh: true,
});

async function checkProxy() {
  const proxy = await rotator.next();
  const agent = new HttpsProxyAgent(`http://${proxy}`);
  return new Promise((resolve, reject) => {
    const request = https.get("https://httpbin.org/ip", { agent }, (response) => {
      let body = "";
      response.setEncoding("utf8");
      response.on("data", (chunk) => { body += chunk; });
      response.on("end", () => resolve({ status: response.statusCode, body }));
    });
    request.setTimeout(15000, () => request.destroy(new Error("Request timed out")));
    request.on("error", reject);
  });
}

checkProxy().then(console.log).catch(console.error);

Practical Tips

  • client.rotator() is synchronous; rotator.next() is asynchronous and returns an ip:port string.
  • Keep PROXY11_API_KEY in an environment variable. Because API keys are query parameters, avoid sharing full request URLs and restrict access to request logs.
  • Only call markDead(proxy) when the proxy connection itself failed; an HTTP error from the destination is a different signal.

Use an agent to route HTTPS

Fetching a proxy address does not route traffic by itself. HttpsProxyAgent establishes the CONNECT tunnel used by the Node HTTPS client. The sample uses a 15-second request timeout; choose a limit that fits your workload.

Pool refresh behavior

The Node rotator keeps a local list and returns one address at a time. autoRefresh lets it fetch a new list when that pool is empty; refreshAfter can also be set to refresh after a chosen number of selections.


Proxy API

Fetch proxy lists in TXT, JSON, CSV, or XML formats.

API documentation

Python SDK

Install with pip and use rotators or requests sessions.

Python GitHub repo

Node.js SDK

Install with npm and use async proxy helpers.

Node.js GitHub repo