Jina Reader turns a URL into clean text for a model, and it has two different proxy headers. People reach for the wrong one, or pass auto and assume it does something clever. This page separates them and shows what the country value resolves to in the code. We read the project at the head of its main branch, commit 1574bfd3 of 22 May 2026; it publishes no releases.
Two headers, not one
| Header | What it does | Needs a key |
|---|---|---|
x-proxy | use the service's own pool, optionally with a country | yes, per their documentation |
x-proxy-url | route through the address you pass | no |
curl https://r.jina.ai/https://example.com \
-H "x-proxy-url: http://USER:PASS@GATEWAY_HOST:GATEWAY_PORT"
The bring-your-own header accepts four schemes: plain HTTP, HTTPS, and both SOCKS versions. For a login, the documented shape puts it inside the address. Both headers are read per request, so the address can change from call to call.
One piece of their own advice belongs before any of this. The project says anonymous traffic is "the most aggressively rate-limited and lands in the lowest-trust pool". Authenticated requests get a higher quota. If you are throttled without a key, that is the cheaper fix.
What "auto" actually means
In the code, auto and true are both normalised to any. Then any becomes a random pick from a list of six countries: the United States, Canada, the United Kingdom, Australia, New Zealand and Singapore. Your own location plays no part, and neither does the target. The pick is a coin toss between those six.
If you care where the request appears to come from, name the country.
There is also a preferred-country environment variable. It is honoured in one of the two allocation paths and ignored in the other. One reads it before falling back to the random pick, the other goes straight to the random pick. We did not establish which path runs for a given request, so treat that variable as a hint.
Running it yourself
The pool is not built into the code. It is assembled at start-up from environment variables that name commercial networks. One is active in this commit and the others are commented out. Until you configure one, a self-hosted reader has an empty pool.
That produces two different messages, and they mean different things:
- No proxy provider found. Nothing is configured at all.
- No proxy provider found that supports country code: xx. Something is configured, but not for the country you asked for.
The second is the more useful error. It tells you the pool is alive, and that your country request is the problem.
Which proxy type fits it?
Residential, passed with the bring-your-own header, for targets that refuse whatever address the reader would use otherwise. Two of the four schemes it accepts are the two we hand out, so either port works.
Our paired test gives the honest ceiling: a residential address changed 4 of 13 answers, and four sites refused both a server address and a residential one. For those four, neither a pool nor your own line is the answer.
Because the header is per request, you can use your own address for the handful of targets that need it. That keeps traffic down, which matters here. The reader fetches whole pages, so a per gigabyte line pays for everything a page pulls in. The residential proxies page lists the plans and the plan API manages allowed addresses from code.
What breaks
- The country you asked for is ignored. You sent
auto, which is a random pick from six countries. - A self-hosted reader refuses every proxied request. The pool is empty until an environment variable names a provider.
- Your preferred country is not used. Only one of the two allocation paths reads that variable.
- You are still rate limited. Check that you are sending a key before you change addresses.
- The target refuses everything. Four of thirteen sites in our test refused both address types.
What this page does not cover
We read the repository as text and did not call the service or run it. So we did not watch a header being honoured, did not measure the hosted pool, and make no claim about its success rate. Which allocation path runs for a given request is not something we established. So the disagreement about that variable is reported as a difference between two functions, not as something you will certainly meet. The project publishes no releases, and the commit we read is from May 2026. The hosted service can also change under the same documentation at any time. We will read it again by 20 October 2026.
Where to go from here
Proxies for Firecrawl covers the other self-hostable reader, where the proxy question is a build-time decision. Proxies for ScrapeGraphAI covers a library with its own built-in proxy finder. Proxies for SearXNG covers the search engine an agent can read alongside this.
Sources
- The two headers and the advice about keys (README), their schema and the code that reads them (src/dto/crawler-options.ts), the country handling, the preferred-country variable and the two error messages (src/services/proxy-provider/index.ts). jina-ai/reader at commit 1574bfd3, 22 May 2026, read 20 September 2026.
- 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.
