Quickstart: your first proxy request

This netdash quickstart takes you from a new account to one request through a netdash gateway, in four steps, and then points you to the reference pages. Plans are bought per GB; the smallest order is 1 GB.

1. Create an account

Sign up with an email address and password and enter the one-time code we email you, or sign in with Google or Discord.

2. Buy a plan

Residential proxies come in three plans: Solve, our lowest-cost residential plan; Scale, our mid-priced plan; and the Opus plan, our highest-priced plan. They differ in which network pool they route to and in price. The connection syntax is identical, so you can switch plans later by changing the host and port. Mobile is a separate plan with mobile exit IPs and the same username syntax. The residential proxies page describes the plans in more detail.

In the shop, pick a plan and an amount from 1 to 50,000 GB. You pay once, in USD, by card through Stripe Checkout, and the plan is provisioned automatically once payment is confirmed. Prices are graduated per order and listed on the pricing page.

3. Copy your credentials

In the dashboard, open Residential (or Mobile for mobile proxies) and use Generate. Choose the plan, the gateway region, the exit country and the session type, and the generator gives you ready-made proxy strings with your username, your password and the gateway host and port.

Your base username and password are the same on every residential and mobile plan. Each plan keeps its own GB balance. The examples on this site write USERNAME and PASSWORD in their place: replace them with your own values.

4. Send your first request

Replace USERNAME and PASSWORD, then run one of these. The example uses the Scale plan on the Americas gateway (scale-us.netdash.io:2000) with a US exit and a rotating session:

curl --max-time 30 -x "http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000" \
  "https://api.ipify.org?format=json"

{"ip":"203.0.113.10"}

import requests

proxy = "http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000"
proxies = {"http": proxy, "https": proxy}  # set both, or HTTPS requests bypass the proxy

response = requests.get("https://api.ipify.org?format=json", proxies=proxies, timeout=30)
response.raise_for_status()
print(response.text)

{"ip":"203.0.113.10"}

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"}

Three details matter:

• The proxy URL starts with http://, also for HTTPS websites. netdash is an HTTP proxy, and HTTPS websites are reached through a CONNECT tunnel.
• Quote the URL in your shell. In zsh, an unquoted ? is a filename pattern, and the command stops with zsh: no matches found.
• Configure the proxy on the client. Python requests picks the proxy by the scheme of the website's URL, so the example sets both the http and the https key; with only http, HTTPS requests go out directly. Node.js's built-in fetch doesn't read HTTPS_PROXY by default, so the example passes a ProxyAgent to fetch, both from the undici package (npm install undici).

To try another plan, country or a sticky session, change the options here and copy the updated code. Use the Americas gateway (-us) for exits in the Americas and the Europe gateway (-eu) for exits in Europe, Africa and Asia. For an exit country in Oceania, ask support which gateway to use.

curl --max-time 30 -x "http://USERNAME-cc-US-session-a1b2c3d4-ttl-10080:PASSWORD@mobile-us.netdash.io:4000" \
  "https://api.ipify.org?format=json"

{"ip":"203.0.113.10"}

import requests

proxy = "http://USERNAME-cc-US-session-a1b2c3d4-ttl-10080:PASSWORD@mobile-us.netdash.io:4000"
proxies = {"http": proxy, "https": proxy}  # set both, or HTTPS requests bypass the proxy

response = requests.get("https://api.ipify.org?format=json", proxies=proxies, timeout=30)
response.raise_for_status()
print(response.text)

{"ip":"203.0.113.10"}

import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent({
  uri: "http://mobile-us.netdash.io:4000",
  token: "Basic " + Buffer.from("USERNAME-cc-US-session-a1b2c3d4-ttl-10080: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"}

import { chromium } from "playwright";

const browser = await chromium.launch({
  proxy: {
    server: "http://mobile-us.netdash.io:4000",
    username: "USERNAME-cc-US-session-a1b2c3d4-ttl-10080",
    password: "PASSWORD",
  },
});
const page = await browser.newPage();
await page.goto("https://api.ipify.org?format=json");
console.log(await page.textContent("body"));
await browser.close();

{"ip":"203.0.113.10"}

curl --max-time 30 -x "http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000" \
  "https://api.ipify.org?format=json"

{"ip":"203.0.113.10"}

import requests

proxy = "http://USERNAME-cc-US:PASSWORD@scale-us.netdash.io:2000"
proxies = {"http": proxy, "https": proxy}  # set both, or HTTPS requests bypass the proxy

response = requests.get("https://api.ipify.org?format=json", proxies=proxies, timeout=30)
response.raise_for_status()
print(response.text)

{"ip":"203.0.113.10"}

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"}

import { chromium } from "playwright";

const browser = await chromium.launch({
  proxy: {
    server: "http://scale-us.netdash.io:2000",
    username: "USERNAME-cc-US",
    password: "PASSWORD",
  },
});
const page = await browser.newPage();
await page.goto("https://api.ipify.org?format=json");
console.log(await page.textContent("body"));
await browser.close();

{"ip":"203.0.113.10"}

Check the result

A working setup prints a JSON object with the exit IP, the address the website sees:

{"ip":"203.0.113.10"}

Your output shows a different address in the country you chose. With a rotating session the exit IP isn't pinned, so a later run can print another address.

If curl prints CONNECT tunnel failed, response 407 or your client reports 407 Proxy Authentication Required, the gateway didn't accept the username or password. Check the password, the base username and the parameters: an uppercase country code such as -cc-US, and -ttl- whenever you use -session-. Troubleshooting lists every cause.

Sessions and countries

To keep the same exit IP across several requests, add a session ID and a lifetime in minutes. This request exits in Germany through the Europe gateway and keeps its exit IP for 30 minutes while that IP stays available:

curl --max-time 30 -x "http://USERNAME-cc-DE-session-a1b2c3d4-ttl-30:PASSWORD@scale-eu.netdash.io:2000" \
  "https://api.ipify.org?format=json"

Run it twice within 30 minutes: as long as the exit IP stays available, both runs print the same address. Use your own session ID for each task: letters and digits only, no hyphens. Sessions explains IDs and lifetimes, and country targeting covers country codes and the choice of gateway.

Setup prompt

If a coding agent such as Claude Code writes the integration for you, paste this prompt into it. It gives the agent the gateways and the username syntax, asks it to read credentials from NETDASH_USERNAME and NETDASH_PASSWORD, to configure the proxy on the HTTP client or browser rather than for the whole process, and to stop instead of retrying when a website shows a challenge.

Add netdash proxy support to this project.

Facts (from https://netdash.io/docs/proxy-format.md):
- netdash is a standard HTTP proxy (HTTPS sites go through CONNECT). No SDK.
- Gateways: Solve plan: solve-{us|eu}.netdash.io:1000; Scale plan: scale-{us|eu}.netdash.io:2000; Opus plan: opus-{us|eu}.netdash.io:3000; Mobile: mobile-{us|eu}.netdash.io:4000. Use -us for exits in the Americas, -eu for exits in Europe, Africa and Asia; ask support for Oceania.
- Username: NETDASH_USERNAME-cc-{COUNTRY} for rotating sessions, or NETDASH_USERNAME-cc-{COUNTRY}-session-{SID}-ttl-{MIN} for sticky sessions. COUNTRY is ISO 3166-1 alpha-2 uppercase (GB, not UK). SID is letters and digits only; MIN is the session lifetime in minutes.
- Password: NETDASH_PASSWORD (the proxy password from the dashboard, not the sign-in password).

Requirements:
- Read NETDASH_USERNAME and NETDASH_PASSWORD from the environment (.env, never commit them). Do not hardcode credentials.
- Configure the proxy on the HTTP client or browser explicitly. Do not export HTTP_PROXY/HTTPS_PROXY globally in the shell that runs the coding agent, and do not add them to the coding agent's settings env either.
- Python requests: set both "http" and "https" in proxies. httpx: use proxy=. Node.js: use undici ProxyAgent with undici fetch. Playwright/Puppeteer: pass the server separately from username and password. Selenium/Chrome takes no proxy credentials: use the local forwarder from https://netdash.io/developers/selenium.md.
- Set timeouts, handle HTTP 407 (wrong credentials) with a clear error, and keep TLS verification on.
- Add a small check that prints the exit IP from https://api.ipify.org?format=json through the proxy.
- netdash does not solve CAPTCHAs. If a site shows a challenge or rate-limits the client, stop and report it instead of retrying.
- Only access sites and data the project is permitted to use, respect robots.txt and rate limits.

Agents can also read llms.txt, which lists every docs page in plain text. The Claude Code guide shows the full setup for Claude Code projects, including a proxied browser through Playwright MCP.

Next steps

• Proxy format reference

  Every endpoint, the username syntax and the three output formats.

• Sessions

  When to rotate, when to stick, and how session IDs and lifetimes work.

• Country targeting

  ISO country codes, GB for the UK, and which gateway to use.

• Troubleshooting

  407 errors, requests that skip the proxy, timeouts and quoting.

• Billing

  Per-plan balances, graduated pricing per order and GB that never expire.

• Python guide

  requests and httpx with credentials from the environment.

• Node.js guide

  undici ProxyAgent with fetch, and axios with https-proxy-agent.

• Claude Code guide

  Proxies in Claude Code projects and for Playwright MCP.

All proxy integration guides are listed in the developer section.

Stuck? See troubleshooting or email support.