Skip to content
Get Started
G2G2
4.7/5
Excellent
Trustpilot

How to use proxies with Crawlee

Create new ProxyConfiguration({ proxyUrls: ["http://USERNAME:PASSWORD@HOST:PORT"] }) and pass it as proxyConfiguration to CheerioCrawler, PlaywrightCrawler or any other Crawlee crawler. With the session pool on (the default), Crawlee pairs each session with one URL from the list.

  • Session Control
  • High Speed
  • Privacy First

What you need

Crawlee handles request queues, retries, sessions and block detection for both plain HTTP and headless-browser crawls, and every crawler takes the same proxy object. You can start on one rotating residential line, then move to sticky lists or a tiered setup without touching your request handlers.

Your credential line

From the dashboard's proxy manager: host (or IP), port, username and password. Convert lists with the proxy list formatter.

Crawlee ready

  • Node.js 16 or later and Crawlee 3: npm install crawlee (or npx crawlee create my-crawler).
  • For browser crawls: npm install playwright and npx playwright install chromium.

Which proxy fits Crawlee?

Both products use the same setup in Crawlee. What changes is how long an IP stays with you.

With a single rotating line in proxyUrls, every session shares the gateway and each new connection gets a fresh IP from the 50M+ pool, even inside one session. Pass a sticky list (5 to 60 minutes or 24 hours) instead when a session's cookies must stay on one IP.

starting from$0.63/GB

Residential IPs in 190+ countries with country, state and city targeting. Rotate on every request or hold a sticky session for up to 90 minutes; GB never expire.

Each ISP URL in proxyUrls is one dedicated US IP, and Crawlee keeps a session on the same URL for its whole life, so a session's cookies always travel with the same IP. With unlimited bandwidth, ISP lines suit daily crawls of the same sites.

starting from$0.75/IP

Dedicated static IPs registered to US and Canadian ISPs. The address stays the same for as long as you hold it, with unlimited bandwidth and HTTP(S) or SOCKS5 access.

credentials

Your CleanProxies credentials

Every product connects over HTTP(S); static ISP and ISP subnet proxies also run SOCKS5 and IP whitelisting. This is what the dashboard gives you to paste into Crawlee.

Static ISP and ISP subnetHTTP(S)SOCKS5IP whitelist
IP:PORT:USER:PASS

One line per dedicated IP. With IP whitelisting on, the line is just IP:PORT and no password is sent.

Rotating residential and mobileHTTP(S)User:pass
HOST:PORT:USER:PASS

Generated in the proxy manager. The username carries the location and session you pick, so generate a new list to change them.

As a URL, for code and most toolshttp://USERNAME:PASSWORD@HOST:PORTsocks5://USERNAME:PASSWORD@HOST:PORT

Use http:// even for HTTPS websites; the TLS session still runs end to end. The socks5:// form is for static ISP and ISP subnet proxies.

How to set up CleanProxies in Crawlee

Four steps, then check the exit IP with the free proxy checker.

  1. 1

    Install Crawlee

    Run npm install crawlee, plus Playwright if you crawl with a real browser.

  2. 2

    Create the proxy configuration

    Put one or more http://USERNAME:PASSWORD@HOST:PORT URLs in proxyUrls.

  3. 3

    Pass it to the crawler

    Add proxyConfiguration to the crawler options and leave useSessionPool and persistCookiesPerSession on.

  4. 4

    Check the exit IP

    Crawl https://api.ipify.org?format=json once and log json.ip in the request handler.

copy & paste

Crawlee proxy examples

Replace the highlighted placeholders with the values from your dashboard. Pick an example to see its code.

Crawlee + CleanProxies

CheerioCrawler with a rotating residential line

crawler.mjsJavaScript
import { CheerioCrawler, ProxyConfiguration } from "crawlee";

const proxyConfiguration = new ProxyConfiguration({
  proxyUrls: ["http://USERNAME:PASSWORD@HOST:PORT"],
});

const crawler = new CheerioCrawler({
  proxyConfiguration,
  maxConcurrency: 20,
  async requestHandler({ request, json, $, log }) {
    if (json) log.info("Exit IP: " + json.ip);
    else log.info(request.url + ": " + $("title").text());
  },
});

await crawler.run(["https://api.ipify.org?format=json"]);
  • proxyInfo in the request handler tells you which proxy a request used. Log proxyInfo.hostname rather than proxyInfo.url, which contains the password.
fix it fast

Troubleshooting Crawlee proxy errors

Verify your exit IP

Run node crawler.mjs. The log line Exit IP: … should show a residential IP in the country you generated, not your server's address.

Open What is my IP? through the proxy to see the address and headers a website receives, or paste up to ten lines into the free proxy checker to test connectivity, latency and exit IP.

Still stuck? Our 24/7 support team answers fast: contact us with the error and the line you used (leave the password out).

Crawlee error fixes
  • 407 errors in the crawler logWhy: Wrong credentials, or @ or : in the password breaking the URL.Copy the line again and percent-encode special characters in the password.
  • Logged-in pages drop the session halfwayWhy: One rotating line is shared by all sessions, so a session's cookies can move between IPs.Pass a sticky residential list (or ISP lines) so every session keeps its own IP.
  • Lots of retired sessions and 403 or 429 responsesWhy: Too many requests per IP for the target, or headers that don't match a real browser.Lower maxConcurrency, use PlaywrightCrawler for protected sites, and add residential IPs as a second tier.
  • Requests go out from your own IPWhy: proxyConfiguration wasn't passed to the crawler, or a null entry is in the URL list.Pass the object as proxyConfiguration and remove empty or null entries (Crawlee treats null as "no proxy").

Crawlee proxy guides

Setup guides and best practices from the CleanProxies blog.

Get the latest insightsAll Blogs

More integrations

Setup guides for tools people run next to Crawlee.

Proxies for sites people reach with Crawlee
All integrations

Crawlee proxy FAQs

Straight answers about running CleanProxies in Crawlee.

Crawlee hands out the URLs in proxyUrls round-robin and remembers which URL each session got. A session keeps its proxy until it is retired, then the replacement session takes the next URL.

Got more questions?All FAQs