Skip to content

Targeting syntax

Country, city, ASN and session are all parameters in the proxy username. This is the full grammar.

The gateway reads targeting from the proxy username, so the same endpoint and password serve every network and every city. Parameters are appended to the proxy user's name as key-value pairs. Order does not matter. Keys and the country and city values are case-insensitive, while a session ID is case-sensitive. An unknown key is rejected with a 407 rather than silently ignored.

Every IP is in South Korea today. country-kr is the only country the gateway accepts, and city and asn do the narrowing inside it.

[res-|isp-|dc-]HANDLE-NAME[-parameter-value]...

  res-|isp-|dc-  optional network prefix
  HANDLE         your account's 6-character handle, shown in the
                 dashboard and returned by GET /api/v1/account
  NAME           the proxy user's name
  parameter      one of the keys in the table below, in any case
  value          letters and digits, no spaces or punctuation;
                 any case, except session IDs (case-sensitive)

Parameters

ParameterValueExampleNotes
country-XXISO 3166-1 alpha-2 codecountry-krAvailable on every network. kr is the only code accepted today, because every IP on the network is in South Korea; any other code is rejected with a 407. Without it the exit IP is still Korean, but include it so the username keeps its meaning when more countries are added.
city-nameOne of seoul, gyeonggi, busan, incheon, daegu, daejeon, gwangju, ulsan, in any casecity-seoulRequires country. Matches the city an upstream in our pool is tagged with, or is passed to a provider that targets cities itself; a city with no matching upstream returns 502. The dashboard lists every accepted city.
asn-NNNNAutonomous system number, 1 to 4294967295asn-64496Residential network only: with an isp- or dc- prefix, or on a proxy user of another network, it is rejected with a 407. Pins the exit IP to one Korean ISP's network. The org field in the ipinfo.io output shows the ASN behind any IP you receive.
session-IDUp to 64 letters and digits of your choosing, case-sensitivesession-a1b2Keeps the same IP for requests that reuse the ID. See Sessions.
sessduration-MINMinutes, 1 to 30sessduration-10How long a session holds its IP. Only meaningful together with session. Without it, the proxy user's default applies.
res- / isp- / dc-Network prefixdc-k7f3q2-acmeGoes at the very front, before the handle, and overrides the network the proxy user was created for. res- traffic is paid from your residential balance; isp- and dc- need a live subscription for that network and use only the IPs allocated to your account.

Rules worth knowing

  • Parameters narrow the pool. country-kr alone matches every IP on the network; city plus asn may match a handful. If nothing matches, the gateway returns a 502 instead of quietly widening the search.
  • city needs country. Today that is always country-kr; the rule exists so a username keeps pointing at one place when more countries are added.
  • City and ASN are matched against the tags of the upstreams in our pool, or passed to a provider that targets them itself. A site using its own geolocation database may still place an exit in a neighbouring city.
  • The whole username, prefix and parameters included, must be sent on every connection. The gateway keeps no state between connections other than sessions.
  • Every part between hyphens must be non-empty: a leading, trailing or doubled hyphen is rejected with a 407.
  • A 407 names the parameter that is wrong only once the request has authenticated, with the right password or from the proxy user's whitelisted address. Until then any problem with the username is answered with a plain invalid credentials, so usernames cannot be probed from outside.

Examples

Each of these is a complete request. Replace k7f3q2 with your handle, acme with your proxy user and PASSWORD with its password.

Any Korean IP, a fresh pick on every connection

curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr:PASSWORD" https://ipinfo.io/json

Seoul only

curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr-city-seoul:PASSWORD" https://ipinfo.io/json

Busan, one IP for up to thirty minutes

curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr-city-busan-session-b9x4m-sessduration-30:PASSWORD" https://ipinfo.io/json

Reuse the ID at least every 5 minutes; a session with no connections for 5 minutes is released early.

One ISP, by ASN

curl -x icn-01.gw.scalardata.ai:7777 -U "k7f3q2-acme-country-kr-asn-64496:PASSWORD" https://ipinfo.io/json

Datacenter network, overriding the proxy user's default

curl -x icn-01.gw.scalardata.ai:7777 -U "dc-k7f3q2-acme-country-kr:PASSWORD" https://ipinfo.io/json

Needs a live datacenter subscription; traffic leaves through the IPs allocated to your account.