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

# Proxy Configuration

> Route your sessions through proxy servers for geo-targeting and IP rotation

Route browser sessions through proxy servers to access geo-restricted content, rotate IPs, and distribute requests across different locations.

<Note>Proxy features require a paid plan.</Note>

## Quick Start

Enable Hyperbrowser's managed proxy network with a single parameter:

<CodeGroup>
  ```typescript Node.js theme={null}
  import { Hyperbrowser } from "@hyperbrowser/sdk";
  import { config } from "dotenv";

  config();

  const client = new Hyperbrowser({
    apiKey: process.env.HYPERBROWSER_API_KEY,
  });

  const session = await client.sessions.create({
    useProxy: true,
  });

  console.log("Session ID:", session.id);
  console.log("WebSocket endpoint:", session.wsEndpoint);
  ```

  ```python Python theme={null}
  from hyperbrowser import Hyperbrowser
  from hyperbrowser.models import CreateSessionParams
  import os
  from dotenv import load_dotenv

  load_dotenv()

  client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

  session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
      )
  )

  print(f"Session ID: {session.id}")
  print(f"WebSocket endpoint: {session.ws_endpoint}")
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "useProxy": true,
    }'
  ```
</CodeGroup>

## Update Proxy on a Running Session

You can update proxy settings on an active session without recreating it by calling `PUT /session/:id/update` with `type: "proxy"`.

* Set `enabled: false` to disable proxying for the current session.
* Set `enabled: true` with `staticIpId` to switch the session onto a static IP.
* Set `enabled: true` with an optional `location` object to use Hyperbrowser's managed proxy network.
* If `location.country` is omitted, Hyperbrowser defaults it to `US`.
* Custom proxy values cannot be set through this update route. If you need `proxyServer`, `proxyServerUsername`, or `proxyServerPassword`, create the session with those values instead.
* Once a session has used managed proxy or static IP, you can disable and re-enable that same proxy type, but you cannot switch between managed proxy and static IP within the same session.

### Managed Proxy Update

Use `location` to target a managed proxy location on an existing session.

<CodeGroup>
  ```typescript Node.js theme={null}
  await client.sessions.updateProxyParams(session.id, {
    enabled: true,
    location: {
      country: "GB",
      city: "london",
    },
  });

  // If country is omitted, it defaults to US.
  await client.sessions.updateProxyParams(session.id, {
    enabled: true,
    location: {
      state: "CA",
    },
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import (
      UpdateSessionProxyLocationParams,
      UpdateSessionProxyParams,
  )

  client.sessions.update_proxy_params(
      session.id,
      UpdateSessionProxyParams(
          enabled=True,
          location=UpdateSessionProxyLocationParams(
              country="GB",
              city="London",
          ),
      ),
  )

  # If country is omitted, it defaults to US.
  client.sessions.update_proxy_params(
      session.id,
      UpdateSessionProxyParams(
          enabled=True,
          location=UpdateSessionProxyLocationParams(
              state="CA",
          ),
      ),
  )
  ```

  ```bash cURL theme={null}
  curl -X PUT https://api.hyperbrowser.ai/api/session/YOUR_SESSION_ID/update \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "proxy",
      "params": {
        "enabled": true,
        "location": {
          "country": "GB",
          "city": "London"
        }
      }
    }'

  curl -X PUT https://api.hyperbrowser.ai/api/session/YOUR_SESSION_ID/update \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "proxy",
      "params": {
        "enabled": true,
        "location": {
          "state": "CA"
        }
      }
    }'
  ```
</CodeGroup>

### Static IP Update

Provide `staticIpId` to move an existing session onto one of your team's active static IPs.

<CodeGroup>
  ```typescript Node.js theme={null}
  await client.sessions.updateProxyParams(session.id, {
    enabled: true,
    staticIpId: "YOUR_STATIC_IP_ID",
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import UpdateSessionProxyParams

  client.sessions.update_proxy_params(
      session.id,
      UpdateSessionProxyParams(
          enabled=True,
          static_ip_id="YOUR_STATIC_IP_ID",
      ),
  )
  ```

  ```bash cURL theme={null}
  curl -X PUT https://api.hyperbrowser.ai/api/session/YOUR_SESSION_ID/update \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "proxy",
      "params": {
        "enabled": true,
        "staticIpId": "YOUR_STATIC_IP_ID"
      }
    }'
  ```
</CodeGroup>

### Disable Proxy

Disable proxying for the active session without ending the session itself.

<CodeGroup>
  ```typescript Node.js theme={null}
  await client.sessions.updateProxyParams(session.id, {
    enabled: false,
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import UpdateSessionProxyParams

  client.sessions.update_proxy_params(
      session.id,
      UpdateSessionProxyParams(
          enabled=False,
      ),
  )
  ```

  ```bash cURL theme={null}
  curl -X PUT https://api.hyperbrowser.ai/api/session/YOUR_SESSION_ID/update \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "proxy",
      "params": {
        "enabled": false
      }
    }'
  ```
</CodeGroup>

## Country-Level Targeting

Target specific countries using ISO 3166-1 alpha-2 country codes. Hyperbrowser supports 100+ countries including:

| Region            | Countries                                      |
| ----------------- | ---------------------------------------------- |
| **North America** | `US`, `CA`, `MX`                               |
| **Europe**        | `GB`, `DE`, `FR`, `ES`, `IT`, `NL`, `SE`, `CH` |
| **Asia Pacific**  | `JP`, `AU`, `SG`, `IN`, `KR`, `HK`, `CN`       |
| **South America** | `BR`, `AR`, `CL`                               |
| **Middle East**   | `AE`, `SA`, `IL`                               |

<CodeGroup>
  ```typescript Node.js theme={null}
  // Target specific countries
  const usSession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
  });

  const gbSession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "GB",
  });

  const jpSession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "JP",
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams

  # Target specific countries
  us_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="US"
      )
  )

  gb_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="GB"
      )
  )

  jp_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="JP"
      )
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "useProxy": true,
      "proxyCountry": "GB"
    }'
  ```
</CodeGroup>

## US State-Level Targeting

For US proxies, target specific states for more precise geo-targeting:

<CodeGroup>
  ```typescript Node.js theme={null}
  // Target California
  const caSession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
    proxyState: "CA",
  });

  // Target New York
  const nySession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
    proxyState: "NY",
  });

  // Target Texas
  const txSession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
    proxyState: "TX",
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams

  # Target California
  ca_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="US",
          proxy_state="CA"
      )
  )

  # Target New York
  ny_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="US",
          proxy_state="NY"
      )
  )

  # Target Texas
  tx_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="US",
          proxy_state="TX"
      )
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "useProxy": true,
      "proxyCountry": "US",
      "proxyState": "CA"
    }'
  ```
</CodeGroup>

<Note>
  State codes use the standard two-letter US state abbreviations (AL, AK, AZ,
  AR, CA, etc.)
</Note>

## City-Level Targeting

Target specific cities for ultra-precise geo-location. Common cities include New York, Los Angeles, Chicago, London, Tokyo, and more.

<CodeGroup>
  ```typescript Node.js theme={null}
  // Target New York City
  const nycSession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
    proxyCity: "New York",
  });

  // Target London
  const londonSession = await client.sessions.create({
    useProxy: true,
    proxyCountry: "GB",
    proxyCity: "London",
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams

  # Target New York City
  nyc_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="US",
          proxy_city="New York"
      )
  )

  # Target London
  london_session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="GB",
          proxy_city="London"
      )
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "useProxy": true,
      "proxyCountry": "US",
      "proxyCity": "New York"
    }'
  ```
</CodeGroup>

<Warning>
  `proxyCity` and `proxyState` are mutually exclusive. Use one or the other, not
  both.
</Warning>

<Note>
  While Hyperbrowser supports nearly all countries and a lot of cities, not all areas are guaranteed to be available. Especially for areas with low population density, separate testing should be done to ensure that adequate coverage is available.
</Note>

## Custom Proxy Servers

<Note>
  Custom proxy servers are only available on the Enterprise plan. Reach out to us at [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai) to learn more.
</Note>

Use your own proxy infrastructure by providing server credentials. Supports HTTP, HTTPS, SOCKS5, SOCKS5h proxies.

<CodeGroup>
  ```typescript Node.js theme={null}
  const session = await client.sessions.create({
    useProxy: true,
    proxyServer: "scheme://proxy.example.com:8080",
    proxyServerUsername: "proxy-username",
    proxyServerPassword: "proxy-password",
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams

  session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_server="scheme://proxy.example.com:8080",
          proxy_server_username="proxy-username",
          proxy_server_password="proxy-password"
      )
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "useProxy": true,
      "proxyServer": "scheme://proxy.example.com:8080",
      "proxyServerUsername": "proxy-username",
      "proxyServerPassword": "proxy-password"
    }'
  ```
</CodeGroup>

<Note>
  When setting the `proxyServer`, ensure that you start it with the scheme like `http://` for example.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Match proxy to content" icon="location-dot">
    Use proxies in the same region as your target content for better performance and to avoid geo-blocking.
  </Accordion>

  {" "}

  <Accordion title="Combine with stealth features" icon="mask">
    Always enable `useUltraStealth` or `useStealth` when using proxies to maximize
    detection evasion.
  </Accordion>

  {" "}

  <Accordion title="Test before scaling" icon="flask">
    Verify your proxy configuration works with target sites before running large-scale operations.
  </Accordion>
</AccordionGroup>

## Related Features

<CardGroup cols={2}>
  <Card title="Stealth Mode" icon="user-secret" href="/sessions/stealth">
    Advanced bot detection evasion
  </Card>

  <Card title="Static IPs" icon="map-pin" href="/sessions/static-ips">
    Use dedicated IP addresses
  </Card>

  <Card title="Profiles" icon="user" href="/sessions/profiles">
    Persist cookies and local storage
  </Card>

  <Card title="Live View" icon="eye" href="/sessions/live-view">
    Watch sessions in real-time
  </Card>
</CardGroup>