Skip to main content
Set the route when you open a session, or change it while the session runs. Tabs and logins stay. Traffic is billed by the network that carried it. See Pricing.

Options

A profile keeps the country it first used. See Profiles. The closing answer’s exitBytes splits traffic by network: managed, direct and custom.

Read and change the route

GET /v1/browser/{session_id}/proxy is free and returns mode, country and exitIp, the address sites see. When it cannot be read, exitIp is null and exitIpError says so. Send the request again. PATCH the same path to change a running session. Open connections end and new ones use the new route. Send one body: A body with nothing to change answers as GET does.

Network policies

A policy is a saved list of domains that several sessions share. Policies are free. A domain such as example.com covers itself and every subdomain, and the most specific entry wins. Domains are trimmed, lower-cased and de-duplicated, and a leading *. is dropped.
This allowlist blocks everything except those two sites. To block a few sites instead, leave defaultAction out, which means allow, and list them in block.domains. The answer has id and version. Open a session with "networkPolicyId": "<id>". It returns networkPolicyVersion, the version it enforces. The policy checks every request, not only the page address. For a short list that belongs to one session, send "allowedDomains": ["example.com"] instead, up to 100 domains, and not with networkPolicyId. A change reaches running sessions within seconds. The answer has runningSessions, appliedSessions, and pendingSessionIds for sessions not reached yet, which keep the old policy until their networkPolicyVersion catches up. A change that blocks a host closes its open connections, counted in closedConnections. A policy holds at most 10,000 domains in allow and block together. An account holds at most 100 policies.

Errors

All return 400 invalidRequest unless noted.
  • location.country with proxy set to direct or a URL. A country needs the default network.
  • A country that is not two letters, a proxy that is not residential, direct or a public URL, or a customProxy.host that is not public, such as localhost.
  • A URL, path, port, IP address, other wildcard, or a domain in both lists in a policy.
  • allowedDomains with networkPolicyId.
  • A session that is not running: 409 invalidRequest.
  • Deleting a policy a running session uses: 409 invalidRequest. Close the session first.
  • An unknown policy: 404 notFound.