Skip to main content
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();
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);
  }
}

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

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

​
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:
  1. 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.
  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: 
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,
});

​
Best Practices

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.
Having a static IP doesn’t mean you can hammer a site. Implement proper delays and rate limiting to stay under the radar.
Set up IP whitelisting well before you need it. Some services take days to process whitelist requests.
Keep notes on which static IPs you’re using for which purposes. Makes troubleshooting and management much easier.
Always test with your static IP in a dev environment before going to production. Verify the IP is working as expected.

​
Troubleshooting

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
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
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
Symptoms: Don’t know what to pass as staticIpIdFixes:
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