Use a proxy in Node.js with undici, fetch and axios

This Node.js proxy guide uses undici, the HTTP client behind Node's own fetch, installed as a package so you can give each request a proxy. netdash is a standard HTTP proxy, so there is no SDK: a ProxyAgent pointed at the gateway with your username and password is all it takes. The examples are ES modules with top-level await: save them as .mjs files, or set "type": "module" in package.json. They were checked with undici 7, which needs Node.js 20.18.1 or later. The current major version, undici 8, needs Node.js 22.19 or later, so on Node.js 20 install undici@7.

Quick start: undici ProxyAgent with fetch

Install undici with npm install undici, replace USERNAME and PASSWORD with the credentials from the dashboard (Residential, then Generate), and run the file:

import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent({
  uri: "http://scale-us.netdash.io:2000",
  token: "Basic " + Buffer.from("USERNAME-cc-US:PASSWORD").toString("base64"),
});

const res = await fetch("https://api.ipify.org?format=json", { dispatcher, signal: AbortSignal.timeout(30_000) });
console.log(await res.text());

{"ip":"203.0.113.10"}

It prints the exit IP the website saw, for example {"ip":"203.0.113.10"}. The proxy URI starts with http:// even though the website is HTTPS: netdash is an HTTP proxy, and HTTPS requests go through a CONNECT tunnel, so TLS still runs end to end between Node and the website.

Import fetch from undici together with ProxyAgent, so the dispatcher and fetch come from the same package version. Node's built-in fetch is a separate copy of undici whose version depends on your Node.js release.

Why built-in fetch ignores HTTPS_PROXY in a Node.js proxy setup

Node's built-in fetch doesn't read HTTP_PROXY or HTTPS_PROXY by default. Setting the variables changes nothing until you opt in with NODE_USE_ENV_PROXY=1 or the --use-env-proxy flag. fetch honors the opt-in from Node.js 22.21.0 or 24.0.0; the http and https modules, and the flag, need Node.js 22.21.0 or 24.5.0. Once enabled, requests use the proxy unless you pass your own agent or the host matches NO_PROXY:

NODE_USE_ENV_PROXY=1 \
HTTPS_PROXY="http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000" \
NO_PROXY="localhost,127.0.0.1" \
node app.mjs

That switch applies to every request the process makes, including calls to model APIs, package registries and your own services. Those requests would go through netdash and count against your balance. An explicit dispatcher on the requests that fetch websites is easier to reason about, which is why the rest of this guide uses one.

Authenticate the proxy

undici offers two documented ways to send your credentials. The token option takes a complete Proxy-Authorization value, such as Basic plus the base64 of username:password, and takes precedence over anything else. Alternatively, put the credentials in the proxy URI: undici URL-decodes them and sends them as Basic authentication. The older auth option is deprecated.

import { ProxyAgent, fetch } from "undici";

const { NETDASH_USERNAME, NETDASH_PASSWORD } = process.env;
const user = encodeURIComponent(`${NETDASH_USERNAME}-cc-US`);
const pass = encodeURIComponent(NETDASH_PASSWORD);

const dispatcher = new ProxyAgent(`http://${user}:${pass}@scale-us.netdash.io:2000`);
const res = await fetch("https://api.ipify.org?format=json", {
  dispatcher,
  signal: AbortSignal.timeout(30_000),
});
console.log(await res.json());
await dispatcher.close();

Sticky sessions and exit countries

The username carries the options: -cc-DE sets the exit country, and -session-{ID}-ttl-{MINUTES} keeps one exit IP for the lifetime you set while that IP stays available. Reusing a session ID reuses the session; a new ID starts a new one. Session IDs use letters and digits only, and randomBytes(4).toString("hex") gives 8 of them, the same length the dashboard generates. Use GB for the United Kingdom, not UK, and the -eu gateway for exits in Europe.

Put the helper in its own module:

import { randomBytes } from "node:crypto";
import { ProxyAgent } from "undici";

const { NETDASH_USERNAME, NETDASH_PASSWORD } = process.env;

export function netdashAgent({ country = "US", sessionId, ttl = 30,
                               gateway = "http://scale-us.netdash.io:2000" } = {}) {
  const cc = country.toUpperCase() === "UK" ? "GB" : country.toUpperCase();
  let username = `${NETDASH_USERNAME}-cc-${cc}`;
  if (sessionId) username += `-session-${sessionId}-ttl-${ttl}`;
  return new ProxyAgent({
    uri: gateway,
    token: `Basic ${Buffer.from(`${username}:${NETDASH_PASSWORD}`).toString("base64")}`,
  });
}

export const newSessionId = () => randomBytes(4).toString("hex");

Then create one agent per sticky session, use it for every request of the task, and close it when the task ends:

import { fetch } from "undici";
import { netdashAgent, newSessionId } from "./netdash.mjs";

// One agent per sticky session: German exit through the Europe gateway
const agent = netdashAgent({ country: "DE", sessionId: newSessionId(),
                             gateway: "http://scale-eu.netdash.io:2000" });
for (let i = 0; i < 2; i++) {
  const res = await fetch("https://api.ipify.org?format=json", {
    dispatcher: agent,
    signal: AbortSignal.timeout(30_000),
  });
  console.log(await res.json()); // the same exit IP both times
}
await agent.close();

The dashboard's sticky presets are 15 minutes, 30 minutes, 12 hours and 7 days; rotating and sticky sessions explains how to choose. For rotating sessions, leave out sessionId and the gateway assigns exit IPs for you.

axios with https-proxy-agent

axios has its own proxy option and also reads http_proxy and https_proxy from the environment. For HTTPS websites, give axios an httpsAgent from https-proxy-agent, which opens a CONNECT tunnel and sends the credentials from the proxy URL as Proxy-Authorization, and set proxy: false so axios ignores its own proxy settings and the environment variables. Install both with npm install axios https-proxy-agent.

import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const { NETDASH_USERNAME, NETDASH_PASSWORD } = process.env;
const proxy = `http://${NETDASH_USERNAME}-cc-US:${NETDASH_PASSWORD}@scale-us.netdash.io:2000`;

const res = await axios.get("https://api.ipify.org?format=json", {
  httpsAgent: new HttpsProxyAgent(proxy),
  proxy: false, // no built-in proxy handling, no proxy environment variables
  timeout: 30_000,
});
console.log(res.data);

For plain http:// websites, pass httpAgent: new HttpProxyAgent(proxy) from the http-proxy-agent package as well. Recent https-proxy-agent releases are ES modules only, which suits the .mjs files used here.

Concurrency without overloading a site

netdash sets no per-account concurrency limit, so the limit that matters is the one each website can handle. A small worker pool over one agent keeps the number of requests in flight fixed, and it stops as soon as the site pushes back with 403 or 429:

import { fetch } from "undici";
import { netdashAgent } from "./netdash.mjs";

const urls = Array.from({ length: 10 }, (_, i) => `https://example.com/catalog?page=${i + 1}`);
const queue = [...urls];
const results = [];
const agent = netdashAgent({ country: "US" });
let stopped = false;

async function worker() {
  while (queue.length > 0 && !stopped) {
    const url = queue.shift();
    const res = await fetch(url, { dispatcher: agent, signal: AbortSignal.timeout(30_000) });
    const body = await res.text();
    if (res.status === 403 || res.status === 429) {
      stopped = true; // the site is pushing back: stop, then check its terms and limits
      console.log(`${res.status} from ${url}, stopping`);
      return;
    }
    results.push({ url, status: res.status, bytes: body.length });
  }
}

await Promise.all(Array.from({ length: 5 }, worker)); // 5 requests in flight at most
console.table(results);
await agent.close();

Errors and fixes

When undici's fetch fails, the message is usually just TypeError: fetch failed. Log err.cause, and the cause of that error in turn, to see what went wrong.

Next steps

Driving a browser instead of an HTTP client? The Playwright proxy setup covers per-browser and per-context proxies. For Python, see the Python requests proxy guide, and for data collection at scale, web data collection. All other tools are in the proxy integration guides. New to netdash? Start with the quickstart and keep the proxy format reference at hand.

• Puppeteer proxy setup

  An authenticated proxy per browser or per context, with the exit country in the username.

• Troubleshooting

  407 errors, timeouts, requests that skip the proxy and the wrong exit country.

• Browser automation

  End-to-end tests and permitted browser workflows from the countries your users are in.

Stuck? See troubleshooting or email support with your username (without the password) and the error message.