ScrapeGraphAI is two things with one name: a hosted service, and the open source library you install. Almost everything written about the name describes the hosted one, where proxies are handled for you. This page is about the library, where they are not. We read release 2.2.4 on 20 September 2026.
Where the proxy goes
graph_config = {
"llm": {"api_key": "API_KEY", "model": "openai/gpt-4o-mini"},
"loader_kwargs": {
"proxy": {
"server": "http://GATEWAY_HOST:GATEWAY_PORT",
"username": "USER",
"password": "PASS",
},
},
"headless": True,
}
It belongs under the loader settings, not next to the model. The shape is the familiar browser one: a server, an optional list of hosts to bypass, and a login.
| Field | What it does |
|---|---|
server | your address, or the literal word broker |
bypass | hosts that skip the proxy |
username, password | the login, which must come as a pair |
criteria | only meaningful with broker |
Two rules are enforced by assertion, which means you meet them as a crash rather than a warning. The server field must be present. And the username and password "must be provided in pairs or not at all", which is the exact message you will see if you supply one of them.
The host itself has to parse as an address or a domain name. Anything else ends in an assertion complaining about an unknown proxy server type.
The word that changes everything
Set the server to the literal string broker and the setting stops meaning your proxy. The library then searches for one:
"proxy": {
"server": "broker",
"criteria": {"anonymous": True, "countryset": {"US"}, "timeout": 5.0},
}
What it searches is a free public proxy list. The library asks that list for candidates matching your criteria, then tests them one at a time and keeps the ones that answered.
The criteria you can express are broad: a minimum anonymity level, a set of countries, whether it should be secure, a timeout, and whether to look outside your countries when nothing matches. There is no session, no stickiness, and nobody who answers for the address. It is a reasonable way to try something. It is not a way to run a job that matters. We have written separately about whether free proxies are safe.
What rotation means here
The module is called proxy rotation, which sets an expectation the code does not meet. The browser loader resolves the setting once, when it is constructed, and reuses the result for the launches that follow. So a broker search happens at that moment, not per page, and your own address is simply used as given.
If you want a new address per run, build a new loader per run. If you want a new address per request, this is not the layer for it.
Which proxy type fits it?
Residential, and your own. Our paired test gives the size of what an address changes: 4 of 13 answers changed, and four sites refused both a server address and a residential one.
The pair rule makes an allowed address especially tidy here. On an HProxy Residential Premium plan your machine's address can be allowed, up to 150 per plan, and then there is no username and no password to keep in pairs at all: just a server line in the configuration. The residential proxies page lists the plans and the plan API manages allowed addresses from code.
One practical note on cost. This library drives a browser, and a browser loads everything a page asks for, so a per gigabyte line is paying for images and fonts as well as text. If that matters, keep the loader headless and limit what you fetch.
What breaks
- An assertion about pairs. You supplied a username without a password, or the reverse.
- "unknown proxy server type". Your server field is neither a host nor the word
broker. - The broker finds nothing. Free lists are volatile. The criteria include an option to search outside your countries when a search comes up empty.
- It worked once and then stopped. With a broker address, that is expected. With your own address, it is the site.
- Nothing rotates. The loader resolved the setting when it was built.
What this page does not cover
We read the release as text and did not run the library, so we did not time a broker search, did not count how many candidates it discards, and did not run a graph end to end. What a free list returns changes minute to minute, so we describe the mechanism rather than judging the outcome of any particular search. The hosted service is outside our scope and is quoted only to mark the boundary. This project releases often and the proxy utility is small enough to be rewritten in a single commit, so we will read it again by 20 October 2026.
Where to go from here
Proxies for DeerFlow covers a research agent that reads pages for a model, where only one of its tools takes a proxy. Proxies for Botasaurus covers a library that does rotate a list for you, and what that costs. Are free proxies safe covers what the broker path is actually reaching for.
Sources
- The settings it accepts, the pair rule, the host check and the broker branch (scrapegraphai/utils/proxy_rotation.py), the browser loader that resolves it (scrapegraphai/docloaders/chromium.py), and the one example in the repository (examples/extras/proxy_rotation.py). ScrapeGraphAI/Scrapegraph-ai, release v2.2.4 of 7 September 2026, read 20 September 2026.
- The company's own description of its hosted platform handling proxy rotation behind the scenes. ScrapeGraphAI company blog, read from our crawled corpus.
- Our paired address test of 19 September 2026: 16 URLs, plain requests, two runs from our server and two through a residential line of our house plan. Raw output is kept in the research folder of our OpenClaw page.
- Plans, allowed addresses and sticky sessions. HProxy documentation, hproxy.com/docs, 20 September 2026.
