Static IPs

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:

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();

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()

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"
  }'

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.

2. Consistent Identity for Authenticated Sessions

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

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);
  }
}

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)

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
    }
  }'

3. Multi-Step Workflows

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

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);
  }
}

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)

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",
  }'

Verifying Your Static IP

Quick check to confirm your static IP is working:

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");

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")

# 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

Getting Started with Static IPs

Manage Static IPs

Purchase and allocate static IPs to your team

Follow these steps to get your own static IPs:

Purchase a plan
- On the Hyperbrowser dashboard, go the Static IPs Tab and choose a plan. Your plan determines how many static IPs you can allocate to your team.
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.
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.
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:

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,
});

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
    )
)

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
  }'

Best Practices

Monitor IP Reputation

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.

Respect Rate Limits

Having a static IP doesn’t mean you can hammer a site. Implement proper delays and rate limiting to stay under the radar.

Whitelist Proactively

Set up IP whitelisting well before you need it. Some services take days to process whitelist requests.

Document Usage

Keep notes on which static IPs you’re using for which purposes. Makes troubleshooting and management much easier.

Test First

Always test with your static IP in a dev environment before going to production. Verify the IP is working as expected.

Troubleshooting

IPs Not Staying Consistent

Symptoms: Different IP on each sessionFixes:

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 to confirm your static IP pool is active

Whitelist Not Working

Symptoms: Can’t access whitelisted servicesFixes:

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

IP Reputation Problems

Symptoms: Getting blocked or flagged by target sitesFixes:

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

Can't Find My Static IP ID

Symptoms: Don’t know what to pass as staticIpIdFixes:

Check the Static IPs Tab in the dashboard
The ID is a UUID format string, not the actual IP address
Contact info@hyperbrowser.ai if you can’t locate it

If you have other Static IP needs, please contact us at info@hyperbrowser.ai.

Next Steps

Proxy Configuration

Learn about proxy options

Stealth Mode

Configure anti-detection

Profiles

Persist browser state

Recordings

Record and replay sessions

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Integrations

Why Use Static IPs?

Use Cases

1. API Access with IP Whitelisting

2. Consistent Identity for Authenticated Sessions

3. Multi-Step Workflows

Verifying Your Static IP

Getting Started with Static IPs

Manage Static IPs

Combining with Other Features

Best Practices

Troubleshooting

Next Steps

Proxy Configuration

Stealth Mode

Profiles

Recordings

​Why Use Static IPs?

​Use Cases

​1. API Access with IP Whitelisting

​2. Consistent Identity for Authenticated Sessions

​3. Multi-Step Workflows

​Verifying Your Static IP

​Getting Started with Static IPs

Manage Static IPs

​Combining with Other Features

​Best Practices

​Troubleshooting

​Next Steps

Proxy Configuration

Stealth Mode

Profiles

Recordings

Why Use Static IPs?

Use Cases

1. API Access with IP Whitelisting

2. Consistent Identity for Authenticated Sessions

3. Multi-Step Workflows

Verifying Your Static IP

Getting Started with Static IPs

Combining with Other Features

Best Practices

Troubleshooting

Next Steps