Targeting

All targeting is expressed in the proxy username.

The shape of a username

Start with your login, then append key and value pairs separated by single dashes. Keys may appear in any order after the login, and each key may appear at most once.

text

<login>[-<key>-<value>]...

Values never contain a dash, because the dash is the separator. City names use underscores, so new_york, not new-york.
Everything is lowercase except session ids, which may mix letters and digits in any case.
An unknown key is refused with 400 AVO_BAD_TARGETING rather than ignored.

The five keys

Targeting keys, formats and rules
Key	Meaning	Format	Rules
cc	Country	Two lowercase letters (ISO 3166-1 alpha-2)	Optional. Without it the gateway picks one country for you, and keeps it for a sticky session.
st	State or region	Lowercase letters, digits and underscores	Requires cc. Only on products that support state targeting.
ct	City	Lowercase, underscores instead of spaces	Requires st. Only on products that support city targeting.
sid	Sticky session id	1 to 32 letters and digits, your choice	Optional. Same id means the same exit address.
ttl	Session lifetime, as an upper bound	Whole minutes, from 1 up to the ceiling of your product	Requires sid. Left out, the session lasts up to 45 minutes. Ceilings: 55 minutes on residential and mobile, 115 minutes on premium residential.

Dependencies are enforced in one direction: a city needs a state, a state needs a country, and a lifetime needs a session. Break one of those and the request fails immediately with 400 AVO_BAD_TARGETING. The response carries that code and nothing about what you sent, so the rules on this page are the place to check.

Worked examples

Example usernames and what they do
Username	Result
USERNAME	Rotating, in a country the gateway picks
USERNAME-cc-de	Exit in Germany
USERNAME-cc-us-st-ca	Exit in California, United States (Premium Residential only)
USERNAME-cc-us-st-ca-ct-los_angeles	Exit in Los Angeles, California (Premium Residential only)
USERNAME-sid-a1b2c3	Sticky: hold one address under session a1b2c3
USERNAME-sid-a1b2c3-ttl-30	Sticky, held for up to 30 minutes
USERNAME-cc-de-sid-a1b2c3-ttl-30	German exit, held for up to 30 minutes

What each product supports

Targeting depth differs by product. Asking for something a product does not offer returns 400 AVO_TARGETING_NOT_SUPPORTED, so a mistake shows up in your logs on the first request instead of in your data a week later.

Targeting support by product
Product	Targeting	Sticky sessions
Residential	Country	Supported
Mobile	Country	Supported
Premium Residential	Country, state & city	Supported

Entry region

Every proxy user also carries an entry region: where your traffic enters our network on its way in. You set it per proxy user in the dashboard (Auto, Europe or North America). It is not a username key, so nothing on this page changes when you switch it. Auto suits most setups; picking the region your own machines sit in can shorten the round trip, and that is the whole of what it does.

The exit country is set by cc alone, so a proxy user entering in North America and targeting cc-de still exits in Germany. If you are unsure, leave it on Auto. No region is ever unavailable, and the region changes your latency and nothing else.

In your code

Targeting changes one string, so switching markets is a change of variable. Here is a German, sticky request in five languages. It works on every product; where a product sells state and city targeting, add -st- and -ct- to the same string.

bash

curl -x gate.avocadoproxies.com:8080 \
     -U "USERNAME-cc-de-sid-a1b2c3-ttl-30:PASSWORD" \
     https://example.com

Build and validate

Compose a username here, pick the product it will run on, and check it against the real parser and that product’s limits from the table above before you ship it.

Proxy string builder

Pick the product your proxy user belongs to, then fill in what you need. Empty fields are left out, which is how the gateway treats them, and anything the product does not offer is disabled. Leave the username and password blank to keep the USERNAME and PASSWORD placeholders in the strings below.

Product

Country targeting · sessions up to 55 min

Username

Password

From your dashboard · checked when you connect, not here

Country (cc)

Two letters

State (st)

Not available on Residential

City (ct)

Not available on Residential

Session (sid)

1 to 32 letters and digits

Session lifetime (ttl)

Minutes, 1 to 55. Needs a session

Targeting is valid for Residential: the grammar and this product's limits both accept these keys. The login half is only checked once you type one; USERNAME and PASSWORD below are placeholders to swap for your own login and password.

Host : port : username : password

gate.avocadoproxies.com:8080:USERNAME:PASSWORD

URL form

http://USERNAME:PASSWORD@gate.avocadoproxies.com:8080