Guide

Automating BitBrowser Profiles with Mobile Proxies

A practical guide to the BitBrowser Local API. Learn how to check a mobile proxy, create a profile with it, open the profile and control it with Playwright or Puppeteer, and close it safely when a run ends or fails.

Narmin Kamilsoy
Narmin Kamilsoy Author
11 min read
Automating BitBrowser Profiles with Mobile Proxies

BitBrowser has a Local API that lets a script do what you would otherwise do by hand in the app: test a proxy, create a profile with that proxy, open the profile and close it again. Once a profile is open, the API returns an address that Playwright, Puppeteer or Selenium can connect to.

This guide walks through that flow with a mobile proxy in Python, and shows how to connect Puppeteer to an existing profile in Node.js. If you have not set up a proxy in BitBrowser before, start with How to Set Up a Mobile Proxy in BitBrowser, which covers the same settings in the app.

1
Check the proxy
/checkagent returns the exit IP.
→
2
Create the profile
/browser/update saves the proxy with it.
→
3
Open and connect
/browser/open returns the ws address for Playwright or Puppeteer.
→
4
Close the profile
/browser/close stops it when the run ends.

The BitBrowser API calls in this guide follow BitBrowser's API documentation. We did not run them against BitBrowser itself, since our test environment runs Linux and BitBrowser is only available for Windows and macOS. How We Checked the Code, near the end, lists what we did check. Test the flow on your own installation before you rely on it.

What You Need

BitBrowser installed and signed in. It runs on Windows 10 or later and macOS 12 Monterey or later.
The Local API URL and port, which BitBrowser shows in its settings.
A mobile proxy endpoint for each profile: host, port, username and password.
Python with the requests and playwright packages, or Node.js 18 or later with puppeteer-core.

For the Python examples, install requests and Playwright. The version is pinned to the one we tested:

Terminal
pip install requests playwright==1.56.0

For the Node.js example, install puppeteer-core. Version 24.43.1 supports Node.js 18 or later, while newer major versions require a newer Node.js:

Terminal
npm i puppeteer-core@24.43.1

The Python snippets below build on each other, so run them in order in one file. In the examples, replace YOUR_PORT with the port from BitBrowser's settings, and proxy-endpoint, 8001, user and pass with your own proxy details.

How the Local API Works

According to BitBrowser's documentation, every call is a POST request with the parameters in the request body, and the examples here send them as JSON. Responses are JSON objects with a success field, and failed calls include a message in msg. The endpoints used in this guide:

Endpoint What it does
POST /checkagent Tests a proxy and returns the exit IP with its location details
POST /browser/update Creates a profile when no id is passed, or changes an existing one
POST /browser/open Starts a profile and returns its connection addresses
POST /browser/close Closes a running profile

A small helper keeps the examples short. It sends the request, stops on HTTP errors, and stops with BitBrowser's error message if a call fails:

Python
import requests

API = "http://127.0.0.1:YOUR_PORT"  # the Local API URL from BitBrowser Settings

def call(path, body):
    res = requests.post(API + path, json=body, timeout=60)
    res.raise_for_status()
    data = res.json()
    if not data.get("success"):
        raise RuntimeError(f"{path} failed: {data.get('msg')}")
    return data

Step 1: Check the Proxy

Before you attach a proxy to a profile, test it with /checkagent. The call takes the host, port and proxy type, plus the username and password if the proxy needs them. The documentation lists the port for this call as a string:

Python
check = call("/checkagent", {
    "host": "proxy-endpoint",
    "port": "8001",
    "proxyType": "http",
    "proxyUserName": "user",
    "proxyPassword": "pass",
})
result = check.get("data") or {}
info = result.get("data") or {}
if not result.get("success") or not info.get("ip"):
    raise RuntimeError(f"Proxy check failed: {check}")
print(info["ip"], info.get("countryCode"), info.get("city"), info.get("timeZone"))

In BitBrowser's documented example response, the check result has its own success field and sits under data.data, with the IP, country, region, city, language, timezone and ZIP code. The code checks that inner result and the IP before it continues. Keep in mind that city labels for mobile IPs often differ between lookup services, so the IP itself is the more reliable value to log. How to Test a Mobile Proxy covers further checks.

Step 2: Create a Profile with the Proxy

/browser/update creates a profile when you do not pass an id. The fingerprint object is required, and BitBrowser's documentation says an empty object gives a random fingerprint. The proxy goes into the same request:

Python
created = call("/browser/update", {
    "name": "profile-a",
    "browserFingerPrint": {},  # an empty object gives a random fingerprint
    "proxyMethod": 2,
    "proxyType": "http",
    "host": "proxy-endpoint",
    "port": 8001,
    "proxyUserName": "user",
    "proxyPassword": "pass",
})
profile_id = (created.get("data") or {}).get("id")
if not profile_id:
    raise RuntimeError(f"No profile id in the response: {created}")

proxyMethod 2 is the default custom proxy method, and proxyType accepts noproxy, http, https, socks5 or ssh. The endpoint reference does not show a response for this call. The Local Service Guide's general success example returns an id inside data, so the code reads the profile ID from data.id and stops with a clear error, including the full response, if it is missing. In that case, check in BitBrowser whether a profile was created anyway.

The same request accepts a refreshProxyUrl field, which BitBrowser describes as the proxy rotate URL. Saving the URL there stores it with the profile. It does not start a rotation by itself. To rotate during a run, call your provider's rotation link the way the provider documents it, then check the exit IP again. A rotation does not guarantee a different public IP every time.

Step 3: Open the Profile and Connect Playwright

/browser/open starts the profile. Its response includes ws, a WebSocket address for the Chrome DevTools Protocol, and http, the same debugging address without the WebSocket path. Playwright connects to the ws address with connect_over_cdp:

Python
from playwright.sync_api import sync_playwright

opened = call("/browser/open", {"id": profile_id})
close_failed = False
try:
    ws = opened["data"]["ws"]
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(ws)
        if not browser.contexts:
            raise RuntimeError("No browser context available")
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://api.ipify.org?format=json")
        print(page.inner_text("body"))
finally:
    try:
        call("/browser/close", {"id": profile_id})
    except Exception as close_error:
        close_failed = True
        print(f"Closing the profile failed: {close_error}")

if close_failed:
    raise SystemExit(1)

The proxy comes from the profile, so you do not set a proxy in Playwright. Playwright's documentation states that the default browser context of a CDP connection is accessible through browser.contexts, and the page at api.ipify.org shows the exit IP the profile uses.

The finally block attempts to close the profile through the API even if a step fails, for example when page.goto() times out. This matters because ending Playwright's connection does not stop the browser, as our connection test below showed. If the close call itself fails, the script prints that error separately, so an earlier error stays visible, and it still ends with a failed exit status even when every other step succeeded. If the response to /browser/open never arrives, the script cannot know whether the profile started, so check in BitBrowser whether it is still open.

browser.close() and browser.disconnect()
●End the automation library's connection
●The BitBrowser profile keeps running
POST /browser/close
✓Asks BitBrowser to close the profile
✓Called in the finally block of both samples

Each run of this script creates a new profile. To continue with the same profile in later runs, save the ID from the first run and pass it to /browser/open instead of running Step 2 again.

Running headless

/browser/open also takes an args array. BitBrowser's documentation gives ["--headless"] as the example for starting a profile without a visible window.

Connect Puppeteer to an Existing Profile

In Node.js, puppeteer-core connects to the same ws address. This example opens a profile you already created, in the app or with Step 2. The package does not download its own browser, which suits this case, since BitBrowser starts its own:

Node.js
const puppeteer = require('puppeteer-core');

const API = 'http://127.0.0.1:YOUR_PORT';

async function call(path, body) {
  const res = await fetch(API + path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(60000),
  });
  if (!res.ok) throw new Error(`${path}: HTTP ${res.status}`);
  const data = await res.json();
  if (!data.success) throw new Error(`${path} failed: ${data.msg}`);
  return data;
}

async function main() {
  const id = 'PROFILE_ID';
  const opened = await call('/browser/open', { id });
  try {
    const browser = await puppeteer.connect({
      browserWSEndpoint: opened.data.ws,
    });
    const page = (await browser.pages())[0] || (await browser.newPage());
    await page.goto('https://api.ipify.org?format=json');
    console.log(await page.evaluate(() => document.body.innerText));
    await browser.disconnect();
  } finally {
    try {
      await call('/browser/close', { id });
    } catch (closeError) {
      console.error('Closing the profile failed:', closeError);
      process.exitCode = 1;
    }
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

browser.disconnect() leaves the browser running, so the finally block attempts to close the profile through the API and reports a failed close separately. If any step fails, including the close call, the script prints the error and sets a non zero exit code, so a scheduled job does not report a failed run as a success. Replace PROFILE_ID with your profile's ID.

Selenium

The /browser/open response also returns the path to a matching chromedriver in data.driver. Selenium can attach to the running profile through the http debugging address with that driver. How to Use Mobile Proxies with Playwright covers proxy setup when you launch browsers yourself instead.

How We Checked the Code

Connection: Playwright and Puppeteer connected to a local Chromium through a CDP address like the one /browser/open returns. The browser kept running after browser.close() and browser.disconnect(), which is why the samples close the profile through the API.
Error handling: we ran the samples against a test server that returns BitBrowser's documented responses. A failed proxy check stopped the script before any profile was created, and a response without a profile ID stopped it before the open step. When a page failed to load, or the close call failed, the script still sent the close request and ended with a failed exit code.
Limit: our test environment runs Linux, so none of this was run against BitBrowser itself. Check the responses on your own installation first.

Tips for Automated Runs

Give each profile its own proxy endpoint. Profiles on the same dedicated mobile endpoint generally use the same exit IP at a given time, and a rotation affects all of them. Whether separate endpoints rotate independently depends on the provider, and separate endpoints alone do not guarantee different public IPs, so compare the exit IPs if that matters.
Log the exit IP at the start of each session, either from /checkagent or from the page itself.
Close profiles through /browser/close when a run ends, rather than relying on the automation library to do it.
Use the HTTP or SOCKS5 endpoint of your proxy. BitBrowser profiles do not take OpenVPN connections.
Keep the Local API on 127.0.0.1 and do not expose it to other networks. Load proxy credentials from environment variables or a secrets file rather than writing them into the script.

Antidetect profiles also expose signals beyond the IP. Mobile Proxies for Antidetect Browsers explains how to check for WebRTC leaks, and Proxy DNS Leaks: How to Check and Prevent Them covers DNS.

FAQ

Do I set the proxy in Playwright or in BitBrowser?

In BitBrowser. The proxy belongs to the profile, and Playwright only connects to the browser that BitBrowser starts.

Where do I find the Local API address?

In BitBrowser's settings. The documentation tells you to install and sign in to BitBrowser, then find the Local API URL and port there.

Can I check a proxy without creating a profile?

Yes. /checkagent tests a proxy on its own and returns the exit IP with its location details.

Can I run the BitBrowser API on Linux?

BitBrowser's download page lists Windows and macOS only, and the Local API runs as part of the app.

Platform terms of service still apply. Automating antidetect profiles through mobile proxies changes how your sessions reach a website. It does not authorize activity that a platform prohibits.

Related Reading

● 99.9% Uptime ⚡ 4G/5G Carrier SIMs HTTP · SOCKS5 · OpenVPN

Dedicated Mobile Proxies for Automated Profiles

PowerProxy provides dedicated mobile connections on real carrier SIMs, with HTTP, SOCKS5, and OpenVPN support. In Amsterdam, PowerProxy offers Odido, KPN, and Vodafone SIMs.

✓HTTP and SOCKS5 endpoints for BitBrowser profiles
✓A physical modem and SIM reserved for you alone
✓Rotation at set times or via API
✓Odido, KPN and Vodafone SIMs in Amsterdam

No credit card required  ·  4.3 / 5 on Trustpilot ★★★★★  ·  1,200+ businesses

Enjoyed this article? Share it with your network
Narmin Kamilsoy
Written by

Narmin Kamilsoy

Contributing author sharing insights and stories on our blog.

WeChat Telegram