Skip to main content
Route your browser sessions through proxy servers to control the geographic location and IP address of your automation.

​
Proxy Levels

Control where the proxy is applied using the level parameter.
LevelDescriptionProsCons
systemApplied at the system level — the instance reboots with the new IPNo IP leakageSlower cold start
chromeApplied directly to ChromeFaster cold startCan leak IP on some edge cases (e.g., WebRTC)
When level is omitted, the proxy is routed to the best available connection that matches the country. 
{
  "proxy": {
    "source": "WebRun",
    "country": "US",
    "level": "system"
  }
}
When using the system level, expect additional cold-start latency as the instance reboots with the new IP. The chrome level avoids this reboot but may expose the original IP in edge cases such as WebRTC connections.

​
Proxy Modes

​
WebRun-Managed Proxies

Specify a country and WebRun assigns a proxy from its residential pool. Charged at $2 per GB of data transfer. Set country to any ISO 3166-1 alpha-2 country code, or "random" to let WebRun pick a location. 
{
  "taskDetails": "Check product prices on amazon.co.uk",
  "startingPoint": "https://amazon.co.uk",
  "proxy": {
    "source": "WebRun",
    "country": "GB"
  }
}
Setting country to "random": 
{
  "proxy": {
    "source": "WebRun",
    "country": "random"
  }
}

​
Custom Proxies

Bring your own proxy server. No additional charge from WebRun — you pay your proxy provider directly. The username and password fields are optional for proxies that don’t require authentication. HTTP proxy: 
{
  "proxy": {
    "source": "custom",
    "type": "http",
    "host": "proxy.example.com",
    "port": "8080",
    "username": "user",
    "password": "pass"
  }
}
SOCKS proxy: 
{
  "proxy": {
    "source": "custom",
    "type": "socks",
    "host": "proxy.example.com",
    "port": "1080"
  }
}

​
Disabling Proxy

To explicitly run without a proxy (the default), set proxy to null or omit it: 
{
  "proxy": null
}

​
Full Examples

​
Single-task session with WebRun proxy

curl -X POST https://connect.webrun.ai/start/run-task \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "taskDetails": "Go to google.de and search for Berlin restaurants",
    "startingPoint": "https://google.de",
    "proxy": {
      "source": "WebRun",
      "country": "DE"
    }
  }'

​
Persistent session with custom proxy

curl -X POST https://connect.webrun.ai/start/start-session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "environmentId": "683a1f2e4b0c1d2e3f4a5b6c",
    "proxy": {
      "source": "custom",
      "type": "http",
      "host": "proxy.example.com",
      "port": "8080",
      "username": "user",
      "password": "pass"
    },
    "initialTask": {
      "taskDetails": "Navigate to the dashboard",
      "startingPoint": "https://app.example.com"
    }
  }'
The proxy field is a top-level session parameter, alongside environmentId and initialTask. It is not nested inside initialTask.

​
Pricing

Proxy ModeCost
WebRun-managed$2 per GB of data transfer
Custom (bring your own)No additional WebRun charge
Data transfer is measured across the entire session. Usage is visible in your dashboard.

​
Best Practices

  • Choose the closest country to your target website’s servers to minimize latency.
  • Use "random" sparingly — a specific country gives more predictable results for locale-sensitive sites.
  • Use custom proxies for high-bandwidth tasks (large file downloads, video scraping) to avoid per-GB charges.
  • Combine with environments — pair a proxy with an environment to maintain consistent cookies and browser state across proxied sessions.
  • Account for cold-start — the 2-3 second proxy setup time is a one-time cost per session, not per task.

Sessions

Session configuration and lifecycle

API Parameters

Full proxy parameter reference

Pricing

Proxy and compute pricing details

Secrets

Provide credentials for authenticated sites