> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webrun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxies

> Route browser sessions through proxy servers for geographic targeting and IP management

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.

| Level    | Description                                                        | Pros              | Cons                                          |
| -------- | ------------------------------------------------------------------ | ----------------- | --------------------------------------------- |
| `system` | Applied at the system level — the instance reboots with the new IP | No IP leakage     | Slower cold start                             |
| `chrome` | Applied directly to Chrome                                         | Faster cold start | Can 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.

<CodeGroup>
  ```json System-level proxy theme={null}
  {
    "proxy": {
      "source": "WebRun",
      "country": "US",
      "level": "system"
    }
  }
  ```

  ```json Chrome-level proxy theme={null}
  {
    "proxy": {
      "source": "WebRun",
      "country": "US",
      "level": "chrome"
    }
  }
  ```
</CodeGroup>

<Info>
  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.
</Info>

***

## 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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, or `"random"` to let WebRun pick a location.

<CodeGroup>
  ```json run-task theme={null}
  {
    "proxy": {
      "source": "WebRun",
      "country": "GB"
    },
    "task": {
      "prompt": "Check product prices on amazon.co.uk",
      "startingUrl": "https://amazon.co.uk"
    }
  }
  ```

  ```json start-session (nested format) theme={null}
  {
    "proxy": {
      "source": "WebRun",
      "country": "GB"
    },
    "task": {
      "prompt": "Check product prices on amazon.co.uk",
      "startingUrl": "https://amazon.co.uk"
    }
  }
  ```
</CodeGroup>

Setting `country` to `"random"`:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "proxy": {
    "source": "custom",
    "type": "http",
    "host": "proxy.example.com",
    "port": "8080",
    "username": "user",
    "password": "pass"
  }
}
```

**SOCKS proxy:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "proxy": null
}
```

***

## Full Examples

### Single-task session with WebRun proxy

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

### Persistent session with custom proxy

```bash theme={null}
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"
    },
    "task": {
      "prompt": "Navigate to the dashboard",
      "startingUrl": "https://app.example.com"
    }
  }'
```

<Note>
  The `proxy` field is a top-level session parameter, alongside `environmentId` and `task`. It is not nested inside `task`.
</Note>

***

## Pricing

| Proxy Mode              | Cost                        |
| ----------------------- | --------------------------- |
| 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](https://app.webrun.ai/usage).

***

## 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](/environments/overview) 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.

***

<CardGroup cols={2}>
  <Card title="Sessions" icon="window-restore" href="/concepts/sessions">
    Session configuration and lifecycle
  </Card>

  <Card title="API Parameters" icon="sliders" href="/api-reference/parameters">
    Full proxy parameter reference
  </Card>

  <Card title="Pricing" icon="credit-card" href="/concepts/pricing">
    Proxy and compute pricing details
  </Card>

  <Card title="Secrets" icon="key" href="/usage-guides/secrets">
    Provide credentials for authenticated sites
  </Card>
</CardGroup>