> ## 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.

# Static IPs

> Use dedicated IP addresses for your sessions

Static IPs give you dedicated IP addresses that stay consistent across sessions. Perfect for API whitelisting, maintaining identity with authenticated sessions, or building reputation without the noise from shared IPs.

## Why Use Static IPs?

Standard proxy rotation gives you a different IP each time. Static IPs give you:

* **Consistency** - Same IP across all your sessions
* **Dedicated** - Your IP, not shared with anyone else
* **Whitelist-ready** - Perfect for APIs and services that only allow known IPs
* **Clean reputation** - Build trust without worrying about what others did with that IP
* **Compliance** - Meet security requirements for fixed source IPs

## Use Cases

### 1. API Access with IP Whitelisting

Many enterprise APIs only accept requests from whitelisted IPs. Here's how to use your static IP:

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

  config();

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

  async function accessWhitelistedAPI() {
    const session = await client.sessions.create({
      useProxy: true, // Make sure to set this to true
      staticIpId: "your-static-ip-id", // Your assigned static IP
    });

    try {
      const browser = await chromium.connectOverCDP(session.wsEndpoint);
      const defaultContext = browser.contexts()[0];
      const page = defaultContext.pages()[0];

      // Access API that requires whitelisted IP
      await page.goto("https://example.com");
      const data = await page.content();
      console.log("API Response:", data);
    } catch (err) {
      console.error("Error accessing whitelisted API:", err);
    } finally {
      await client.sessions.stop(session.id);
    }
  }

  accessWhitelistedAPI();
  ```

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

  load_dotenv()

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


  def access_whitelisted_api():
      session = client.sessions.create(
          params=CreateSessionParams(
              use_proxy=True,  # Make sure to set this to True
              static_ip_id="your-static-ip-id",  # Your assigned static IP
          )
      )

      try:
          with sync_playwright() as p:
              browser = p.chromium.connect_over_cdp(session.ws_endpoint)
              default_context = browser.contexts[0]
              page = default_context.pages[0]

              # Access API that requires whitelisted IP
              page.goto("https://example.com")
              data = page.content()
              print(f"API Response: {data}")
      except Exception as e:
          print(f"Error accessing whitelisted API: {e}")
      finally:
          client.sessions.stop(session.id)


  access_whitelisted_api()
  ```

  ```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,
      "staticIpId": "your-static-ip-id"
    }'
  ```
</CodeGroup>

<Warning>
  It is important that you have `useProxy`/`use_proxy` set to `true`/`True` along with your `staticIpId`/`static_ip_id` in your session params when using Static IPs.
</Warning>

### 2. Consistent Identity for Authenticated Sessions

Combine static IPs with profiles to maintain consistent identity across sessions:

<CodeGroup>
  ```typescript Node.js theme={null}
  async function maintainAuthenticatedSession(profileId, staticIpId) {
    const session = await client.sessions.create({
      useProxy: true, // Make sure to set this to true
      staticIpId: staticIpId,
      profile: {
        id: profileId,
        persistChanges: true,
      },
    });

    try {
      const browser = await chromium.connectOverCDP(session.wsEndpoint);
      const defaultContext = browser.contexts()[0];
      const page = defaultContext.pages()[0];

      // Access authenticated content
      // Same IP + saved cookies = consistent identity
      await page.goto("https://example.com/");
    } catch (err) {
      console.error("Error accessing authenticated session:", err);
    } finally {
      await client.sessions.stop(session.id);
    }
  }
  ```

  ```python Python theme={null}
  def maintain_authenticated_session(profile_id: str, static_ip_id: str):
      session = client.sessions.create(
          params=CreateSessionParams(
              use_proxy=True, // Make sure to set this to true
              static_ip_id=static_ip_id,
              profile=CreateSessionProfile(
                  id=profile_id,
                  persist_changes=True
              )
          )
      )

      try:
          with sync_playwright() as p:
              browser = p.chromium.connect_over_cdp(session.ws_endpoint)
              default_context = browser.contexts[0]
              page = default_context.pages[0]

              # Access authenticated content
              # Same IP + saved cookies = consistent identity
              page.goto("https://example.com/")
      except Exception as e:
          print(f"Error accessing authenticated session: {e}");
      finally:
          client.sessions.stop(session.id)
  ```

  ```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,
      "staticIpId": "your-static-ip-id",
      "profile": {
        "id": "your-profile-id",
        "persistChanges": true
      }
    }'
  ```
</CodeGroup>

### 3. Multi-Step Workflows

Some sites flag IP changes mid-session as suspicious. Static IPs keep you consistent:

<CodeGroup>
  ```typescript Node.js theme={null}
  async function performMultiStepWorkflow(staticIpId) {
    const session = await client.sessions.create({
      useProxy: true, // Make sure to set this to true
      staticIpId: staticIpId,
    });

    try {
      const browser = await chromium.connectOverCDP(session.wsEndpoint);
      const defaultContext = browser.contexts()[0];
      const page = defaultContext.pages()[0];

      // Multi-step process with consistent IP
      await page.goto("https://example.com/step1");
      // ... complete step 1

      await page.goto("https://example.com/step2");
      // ... complete step 2

      await page.goto("https://example.com/step3");
      // ... complete step 3

      // All steps appear from the same IP

    } catch (err) {
      console.error("Error performing multi-step workflow:", err);
    } finally {
      await client.sessions.stop(session.id);
    }
  }
  ```

  ```python Python theme={null}
  def perform_multi_step_workflow(static_ip_id: str):
      session = client.sessions.create(
          params=CreateSessionParams(
              use_proxy=True, // Make sure to set this to true
              static_ip_id=static_ip_id,
          )
      )

      try:
          with sync_playwright() as p:
              browser = p.chromium.connect_over_cdp(session.ws_endpoint)
              default_context = browser.contexts[0]
              page = default_context.pages[0]

              # Multi-step process with consistent IP
              page.goto("https://example.com/step1")
              # ... complete step 1

              page.goto("https://example.com/step2")
              # ... complete step 2

              page.goto("https://example.com/step3")
              # ... complete step 3

              # All steps appear from the same IP

      except Exception as e:
          print(f"Error performing multi-step workflow: {e}");
      finally:
          client.sessions.stop(session.id)
  ```

  ```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,
      "staticIpId": "your-static-ip-id",
    }'
  ```
</CodeGroup>

## Verifying Your Static IP

Quick check to confirm your static IP is working:

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

  config();

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

  async function verifyStaticIP(staticIpId) {
    const session1 = await client.sessions.create({
      useProxy: true, // Make sure to set this to true
      staticIpId: staticIpId,
    });

    const session2 = await client.sessions.create({
      useProxy: true, // Make sure to set this to true
      staticIpId: staticIpId,
    });

    try {
      // Check IP from first session
      const browser1 = await chromium.connectOverCDP(session1.wsEndpoint);
      const defaultContext = browser1.contexts()[0];
      const page1 = defaultContext.pages()[0];
      await page1.goto("https://api.ipify.org?format=json");
      const ip1 = await page1.evaluate(() => document.body.textContent);

      // Check IP from second session
      const browser2 = await chromium.connectOverCDP(session2.wsEndpoint);
      const defaultContext2 = browser2.contexts()[0];
      const page2 = defaultContext2.pages()[0];
      await page2.goto("https://api.ipify.org?format=json");
      const ip2 = await page2.evaluate(() => document.body.textContent);

      console.log("Session 1 IP:", ip1); // Should be the same as the static IP address shown in the dashboard
      console.log("Session 2 IP:", ip2); // Should be the same as the static IP address shown in the dashboard
      console.log("IPs match:", ip1 === ip2); // Should be true
    } catch (err) {
      console.error("Error verifying static IP:", err);
    } finally {
      await client.sessions.stop(session1.id);
      await client.sessions.stop(session2.id);
    }
  }
  verifyStaticIP("your-static-ip-id");
  ```

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

  load_dotenv()

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


  def verify_static_ip(static_ip_id: str):
      session1 = client.sessions.create(
          params=CreateSessionParams(use_proxy=True, static_ip_id=static_ip_id)
      )

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

      try:
          with sync_playwright() as p:
              # Check IP from first session
              browser1 = p.chromium.connect_over_cdp(session1.ws_endpoint)
              default_context = browser1.contexts[0]
              page1 = default_context.pages[0]
              page1.goto("https://api.ipify.org?format=json")
              ip1 = page1.evaluate("() => document.body.textContent")

              # Check IP from second session
              browser2 = p.chromium.connect_over_cdp(session2.ws_endpoint)
              default_context2 = browser2.contexts[0]
              page2 = default_context2.pages[0]
              page2.goto("https://api.ipify.org?format=json")
              ip2 = page2.evaluate("() => document.body.textContent")

              print(
                  f"Session 1 IP: {ip1}"
              )  # Should be the same as the static IP address shown in the dashboard
              print(
                  f"Session 2 IP: {ip2}"
              )  # Should be the same as the static IP address shown in the dashboard
              print(f"IPs match: {ip1 == ip2}")  # Should be True
      except Exception as e:
          print(f"Error verifying static IP: {e}")
      finally:
          client.sessions.stop(session1.id)
          client.sessions.stop(session2.id)


  verify_static_ip("your-static-ip-id")
  ```

  ```bash cURL theme={null}
  # Create two sessions with the same static IP
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "useProxy": true,
      "staticIpId": "your-static-ip-id"
    }'

  # Both sessions will use the same IP address
  # Connect to each liveUrl or wsEndpoint and check IP at https://api.ipify.org
  ```
</CodeGroup>

## Getting Started with Static IPs

<Card title="Manage Static IPs" icon="location-dot" href="https://app.hyperbrowser.ai/settings?tab=static-ips">
  Purchase and allocate static IPs to your team
</Card>

Follow these steps to get your own static IPs:

1. **Purchase a plan**
   * On the Hyperbrowser dashboard, go the [Static IPs Tab](https://app.hyperbrowser.ai/settings?tab=static-ips) and choose a plan. Your plan determines how many static IPs you can allocate to your team.

2. **Allocate IPs to your team**
   * On the same page, once you have purchased a plan, allocate available static IPs to your team.
   * You can deactivate or delete an IP from your team at any time.
   * Once a Static IP is deleted from your team, there is no guarantee that it will be available again.

3. **Copy your Static IP ID(s)**
   * After allocation, copy the `ID` shown for the Static IP in the table. Use this ID in your session configuration.
   * The table also contains the actual IP address of the Static IP.

4. **Manage limits and upgrades**
   * Your total allocatable IPs are limited by your plan. Upgrade your plan to increase your static IP allocation.
   * If you downgrade or cancel your plan, any Static IPs over your allocation limit will be randomly deactivated.

## Combining with Other Features

Static IPs work great with other Hyperbrowser capabilities:

<CodeGroup>
  ```typescript Node.js theme={null}
  const session = await client.sessions.create({
    // Static IP
    useProxy: true,
    staticIpId: "your-static-ip-id",

    // Anti-detection
    useUltraStealth: true,

    // Profile persistence
    profile: {
      id: profileId,
      persistChanges: true,
    },

    // Privacy features
    adblock: true,
    trackers: true,
    annoyances: true,

    // Captcha solving
    solveCaptchas: true,
  });
  ```

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

  session = client.sessions.create(
      params=CreateSessionParams(
          # Static IP
          use_proxy=True,
          static_ip_id="your-static-ip-id",

          # Anti-detection
          use_ultra_stealth=True,

          # Profile persistence
          profile=CreateSessionProfile(
              id=profile_id,
              persist_changes=True
          ),

          # Privacy features
          adblock=True,
          trackers=True,
          annoyances=True,

          # Captcha solving
          solve_captchas=True
      )
  )
  ```

  ```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,
      "staticIpId": "your-static-ip-id",
      "useUltraStealth": true,
      "profile": {
        "id": "your-profile-id",
        "persistChanges": true
      },
      "adblock": true,
      "trackers": true,
      "annoyances": true,
      "solveCaptchas": true
    }'
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Monitor IP Reputation" icon="chart-line">
    Keep an eye on your static IP's reputation. If a target site starts blocking it, you may need to adjust your automation patterns or rotate to a different static IP.
  </Accordion>

  <Accordion title="Respect Rate Limits" icon="gauge">
    Having a static IP doesn't mean you can hammer a site. Implement proper delays and rate limiting to stay under the radar.
  </Accordion>

  <Accordion title="Whitelist Proactively" icon="list-check">
    Set up IP whitelisting well before you need it. Some services take days to process whitelist requests.
  </Accordion>

  <Accordion title="Document Usage" icon="book">
    Keep notes on which static IPs you're using for which purposes. Makes troubleshooting and management much easier.
  </Accordion>

  <Accordion title="Test First" icon="flask">
    Always test with your static IP in a dev environment before going to production. Verify the IP is working as expected.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="IPs Not Staying Consistent" icon="circle-exclamation">
    **Symptoms:** Different IP on each session

    **Fixes:**

    * Check that `staticIpId` is set correctly in your session params
    * Make sure that you have `useProxy`/`use_proxy` set to `true`/`True` in your session params
    * Make sure you're using the correct static IP ID (not the actual IP address)
    * Contact [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai) to confirm your static IP pool is active
  </Accordion>

  <Accordion title="Whitelist Not Working" icon="ban">
    **Symptoms:** Can't access whitelisted services

    **Fixes:**

    * Double-check the service whitelisted the correct IP addresses
    * Verify no additional firewall rules are blocking you
    * Confirm the service completed their whitelist setup
    * Test with a simple curl command first to isolate the issue
    * Contact the service provider to verify whitelist status
  </Accordion>

  <Accordion title="IP Reputation Problems" icon="flag">
    **Symptoms:** Getting blocked or flagged by target sites

    **Fixes:**

    * Review your automation - are you being too aggressive?
    * Add delays and proper rate limiting
    * Check if you're respecting robots.txt
    * Contact support to discuss IP rotation or getting a fresh IP
    * Consider using multiple static IPs to distribute load
  </Accordion>

  <Accordion title="Can't Find My Static IP ID" icon="question">
    **Symptoms:** Don't know what to pass as `staticIpId`

    **Fixes:**

    * Check the [Static IPs Tab](https://app.hyperbrowser.ai/settings?tab=static-ips) in the dashboard
    * The ID is a UUID format string, not the actual IP address
    * Contact [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai) if you can't locate it
  </Accordion>
</AccordionGroup>

<Note>
  If you have other Static IP needs, please contact us at [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai).
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Proxy Configuration" icon="globe" href="/sessions/proxy">
    Learn about proxy options
  </Card>

  <Card title="Stealth Mode" icon="user-secret" href="/sessions/stealth">
    Configure anti-detection
  </Card>

  <Card title="Profiles" icon="user" href="/sessions/profiles">
    Persist browser state
  </Card>

  <Card title="Recordings" icon="video" href="/sessions/recordings">
    Record and replay sessions
  </Card>
</CardGroup>