Skip to main content
Every browser session reaches the web one of three ways: as a visitor from a country, through a proxy of your own, or with no proxy. You pick it when you open the session, and you can change it while the session runs, with its tabs and logins kept.

Choose a country

Get an API key in the Quickstart. Send location.country, a two-letter code such as DE or JP. Sites see a visitor from that country. With no choice, the country is the United States.
A country only works with the default network. A session that sends location.country with proxy set to direct or to your own proxy returns 400 invalidRequest.

Read where a session appears

GET /v1/browser/{session_id}/proxy shows how a running session reaches the web. It is free.
exitIp is the address sites see, shown here as an example address. Loading https://api.country.is in that session answered with the same address and "country":"DE". When the address cannot be read, exitIp is null and exitIpError says so. Send the request again.

Change it while the session runs

PATCH /v1/browser/{session_id}/proxy changes the network of a running session. Open tabs and logins stay. Connections open now end, and new ones use the new network. Send one of these bodies:
The same page load now answered "country":"JP". Sending { "rotate": true } kept jp and returned a different exitIp. Sending { "mode": "direct" } returned "country": null. A body with nothing to change answers as GET does.

Use your own proxy

Send your proxy’s address as proxy when you open the session. It must be an http, https, socks5 or socks5h URL on a public host.
To switch a running session to your proxy, send mode custom with customProxy.
host and port are required. protocol is http, https, socks5 or socks5h. A host that is not public, such as localhost, returns 400 invalidRequest with customProxy: host must be a public address.

Options

A profile keeps the country it first used. See Profiles.

Price

Traffic is billed when the session closes, by the choice that carried it. Traffic before and after a change is billed at the rate of its own network. The closing answer’s exitBytes splits the bytes: managed for the default network, direct and custom. This real session spent 38,137 bytes in Japan and 13,328 bytes with no proxy, and its traffic and time cost $0.006 together.
Browser time is $0.06 per hour whatever you choose. See Browser sessions.

Limits and errors

  • location.country with proxy of direct or your own URL returns 400 invalidRequest: location.country picks a residential exit. Leave it out with your own proxy or direct.
  • A country that is not two letters returns 400 invalidRequest: location.country: Expected a two-letter country code such as DE.
  • A proxy that is not residential, direct or a public URL returns 400 invalidRequest: proxy: Expected residential, direct, or your own proxy as an http://, https:// or socks5:// URL on a public host.
  • Reading or changing a session that is not running returns 409 invalidRequest with This browser session is not running.