CAPABILITY · NETWORK
One country pins the exit and the browser identity
A single `country` field sets the residential exit AND the browser locale and timezone, so a site cannot serve a different language than the exit you asked for — or bring your own proxy and keep both.
"country": "de" · "proxy": "http://user:pass@host:port"Capability
Inside egress, geo & locale
Egress and browser identity are two halves of one thing, and the usual failure is letting them disagree: a German exit IP on a browser announcing en-US is a mismatch a site can see. Here one `country` field drives both — the residential exit and the browser locale and timezone — with explicit overrides when you actually want them apart. Bring your own proxy and it is passed through untouched.
One field, both halves
Set `country` (ISO-2, e.g. "de") and the platform pool exits from that country while the browser takes the matching locale and timezone. `locale` and `timezoneId` override individually when you need them to.
Residential or mobile
`proxyType` chooses the platform tier: residential by default, or mobile for carrier IPs — the highest-reputation exit, and the one to reach for when reputation is the constraint.
Bring your own
Pass a `proxy` URL and the run egresses through your own IP untouched. `platformProxy: false` opts out of the platform sticky default entirely.
Sticky, or deliberately not
A run with an account label pins a stable egress identity for that account. `proxyRotate` forces per-request rotation instead — the anonymous-scraping stance, and the opposite of account stickiness.
How it works
The mechanism, in execution order
4 stages, in the order the runtime performs them — not a summary of them.
- 1Choose the exitSet `country` on the run (or `proxy: { type, country }`), or hand over your own proxy URL.
- 2Derive the identityUnless you override them, the browser locale and timezone are derived from the same country, so the two halves cannot disagree.
- 3Pin or rotateAn account or sessionKey pins a stable egress for that identity; proxyRotate forces rotation for anonymous work.
- 4ExecuteThe session opens through the chosen egress and the site sees the network, language and clock you asked for.
In practice
A call you can paste and run
One country field is the honest default: the exit and the browser agree because they come from the same value.
# Platform pool, German exit — locale and timezone follow automatically
curl -X POST https://twin-browser.com/api/v1/run \
-H "Authorization: Bearer $TWIN_API_KEY" \
-H "content-type: application/json" \
-d '{"url":"https://store.example.com","prompt":"read the listed price and availability",
"success":{"kind":"extracted"},
"country":"de","proxyType":"residential"}'
# Override the derived identity only when you mean to
# "country":"de", "locale":"en-GB", "timezoneId":"Europe/London"
# Or your own egress, passed through untouched
# "proxy":"http://user:pass@host:port"- Choose the exitdone
- Derive the identityrunning
- Pin or rotatequeued
- Executequeued
What it costs, how to switch it on
Priced from the same rate card the API serves
Every credit figure on this page is read from the rate card behind GET /api/v1/pricing — it is not typed into the copy, so it cannot drift from what you are billed.
No separate charge — egress is metered
There is no per-proxy line item. Egress bytes are part of the metered cost that the higher-of settlement compares against a run's flat floor, so a heavy page through a residential exit can bill above the 10-credit floor while a light one bills the floor. Setting blockAssets cuts proxy bandwidth directly; it defaults ON when a proxy is set.
Turning it on
- 1Set a countryAdd `country` to any run, job, screenshot, extract or crawl body. The geo fields are forwarded on every browser-launching endpoint.
- 2Pick a tier if reputation matters`proxyType: "mobile"` routes through carrier IPs. Use it when residential is not enough, not as a default.
- 3Or bring your ownPass `proxy` as a URL. Add `platformProxy: false` if you want the platform default out of the way entirely.
- 4Decide sticky vs rotatingUse `account` for work tied to an identity; `proxyRotate: true` for anonymous reads where stickiness is the wrong shape.
At a glance
The contract, in the fewest rows that say it
| Property | Twin Browser |
|---|---|
| Exit country | `country` / `region` (ISO-2) |
| Tier | `proxyType`: residential (default) · mobile |
| Locale | Derived from country; `locale` overrides |
| Timezone | Derived from country; `timezoneId` overrides |
| BYO | `proxy` URL · `platformProxy: false` |
| Stickiness | `account` / `sessionKey` · `proxyRotate` |
Limits
Where it stops, and what it deliberately does not do
A capabilities page with no limits section is a brochure. These are the ceilings, the defaults that will surprise you, and the things this capability is not.
Limits and defaults
- `country` is an ISO-2 code and a malformed value is a 400, not a silent fallback.
- Rotation and stickiness are opposites. Setting proxyRotate on an account-bound run defeats the identity you were protecting.
- `blockAssets` defaults ON when a proxy is set. Turn it off explicitly for a recorded run, or the video has no images.
- A geo field only takes effect on endpoints that launch a browser. Sending one to a control-plane endpoint does nothing.
What it does not do
- It does not spoof a location the exit does not have. The locale follows the country because the exit does; it is not a claim without a route behind it.
- It does not clear a bot wall on its own. Egress is one input to how a site treats you — see the stealth tier for what happens when a run is actually turned away.
- It does not guarantee a specific city or ASN. The pin is a country.
- It does not audit your own proxy. A BYO proxy is passed through untouched, including its failure modes.
FAQ
Questions about egress, geo & locale
Do I need my own proxy provider?
Why does one field set both the exit and the locale?
When should I use the mobile tier?
How do I keep the same IP across runs for one account?
Keep reading
The rest of the platform
The capabilities this one works with, the tools that expose it, the guides that use it end to end, and the vocabulary behind it.
Stealth tier
A full desktop browser profile — real Chrome, human-calibrated timing, residential egress — behind a plan gate and an explicit authorization attestation, billed per success.
Account cadence governor
A per-account, per-host governor caps how fast one identity may be re-poked and puts it on cooldown after a ban signal — answering 429 with Retry-After instead of burning the account.
Connected accounts & handoff
Mint a single-use link, your end user completes the sign-in in a hosted browser, and the captured session makes every later run already logged in — with no password anywhere.
Tools that expose it
Guides
Put your agent to work. Keep the decision.
Start free. Hand your agent a goal on a site you authorize, set the guardrails, and let the first successful run compile the skill every run after it replays.