Proxies & Geo-Targeting
OmniScrape routes scrape requests through residential IPs. You can pin a country, control how IPs rotate, and connect directly via gateway credentials.
The proxy field
Pass a proxy tag in the proxy field of POST /v1/scrape:
residential:<country>
residential:<country>:<rotation-mode>
Both parts are optional. Examples:
| Value | Meaning |
|---|---|
| (omitted) | Auto-pick a healthy IP |
residential:us | US residential IP, sticky (default mode) |
residential:de:rotate | German IP, fresh one on every request |
residential:jp:smart | Japanese IP, reuse until blocked then swap |
residential:global:rotate | Any country, rotating |
Geo-targeting
Use ISO 3166-1 alpha-2 country codes. We support 217 countries.
{
"url": "https://shop.example.com",
"proxy": "residential:de"
}
Common codes: us, gb, de, fr, ca, au, jp, br, in, nl, sg, id.
Prices, product availability, language, and page layout often differ by country. Geo-targeting ensures you collect the exact regional view you need.
IP rotation modes
The third colon-segment controls how IPs rotate. Three modes are available:
| Mode | Behaviour |
|---|---|
sticky (default) | Same IP reused for all requests in a session |
rotate | Fresh IP on every request |
smart | Reuses same IP, automatically mints a new session if blocked |
See Proxy Rotation Modes for full details and examples.
Sticky IPs and sessions
To keep the same IP across multiple requests, combine a session_id with sticky (or just omit the mode — it defaults to sticky):
{
"url": "https://shop.example.com/de/page/1",
"proxy": "residential:de",
"session_id": "de-shop-crawl"
}
All requests with the same session_id share one IP and accumulate cookies. See Sessions.
Direct proxy gateway
Unlocked accounts (PAYG or a plan) get gateway credentials in Dashboard → Proxies for proxy.omniscrape.io:
| Protocol | Port |
|---|---|
| HTTP | 8080 |
| HTTPS | 8443 |
| SOCKS5 | 1080 |
Append _country-<CC> to the proxy username for geo-targeting. Rotate the password from the dashboard or via POST /auth/rotate-proxy-credentials.
Raw proxy fetch (no unlocking)
If you only need a residential IP to fetch a non-protected URL without JS rendering or anti-bot solving, use the proxy fetch endpoint. Billed by bandwidth ($2.00/GB) instead of per request. Requires PAYG or a plan (not available on trial).