How targeting works
Targeting narrows which exit IP you get. There are two ways to send it, and they are interchangeable, so pick whichever suits your client.
Options go on the password
Section titled “Options go on the password”With username and password auth, you append -option-value to the password.
Not the username.
This is the single most common mistake. Your real password still authenticates, because we strip the modifier run before checking it. A modifier bolted onto the username is just a username we do not recognize.
Order does not matter and you can stack as many as you like:
curl -x USERNAME:PASSWORD-country-US-region-texas-city-dallas-session-abc123@us-east.gw.rayobyte.com:8000 \ https://checkip.amazonaws.comOr send headers
Section titled “Or send headers”Under IP whitelisting there is no
password to append to, so every option has an X-Rayobyte-* equivalent. They
work with password auth too.
curl --proxy-header "X-Rayobyte-Country: US" \ --proxy-header "X-Rayobyte-City: dallas" \ -x us-east.gw.rayobyte.com:8000 https://checkip.amazonaws.comSend both forms for the same option and the header wins.
The options
Section titled “The options”| Option | Password form | Header |
|---|---|---|
| Country | -country-US | X-Rayobyte-Country |
| State or region | -region-texas | X-Rayobyte-Region |
| City | -city-dallas | X-Rayobyte-City |
| ZIP code | -zip-75201 | X-Rayobyte-Zip |
| ASN | -asn-7018 | X-Rayobyte-Asn |
| Device OS | -os-windows | X-Rayobyte-Os |
| IP version | -v4 / -v6 | — |
| Sticky session | -session-abc123 | X-Rayobyte-Session |
| Strict sticky | -hardsession-abc123 | X-Rayobyte-Hardsession |
| Duration | -duration-30 | X-Rayobyte-Duration |
Every one is listed with its exact value rules on All parameters.
Narrowing, and the empty pool
Section titled “Narrowing, and the empty pool”Options combine with AND. -country-US-city-dallas means an exit that is in the
US and in Dallas.
Narrow far enough and you will find combinations no exit matches. That returns a failure, not a looser match. We never quietly hand you a different city because the one you asked for was empty. See Errors & retries.
Blocked locations and networks
Section titled “Blocked locations and networks”Some targets are refused outright: the sanctioned countries Cuba, Iran, North
Korea and Syria, the occupied regions of Ukraine, Washington, DC, and the networks
of governments, banks and other sensitive operators. Asking for one returns 451
with the header X-Rayobyte-Block-Reason: targeting, not a 551.
Acceptable use
has the full list. If a block affects a legitimate business purpose, contact
support and we’ll review your use case.
Options a product does not offer
Section titled “Options a product does not offer”Scale Residential has no location targeting and
discards the options. Sending -city-dallas to it does not error and does not narrow
anything.
Rotating ISP and
Rotating DC do not discard them.
On either tier, a country with no exits returns 551 rather than a
looser match, and other location options can too.
Check Feature availability before you build a pipeline around an option.
Was this page helpful?
Thanks. That helps us fix it.