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.
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.
/checkagent returns the exit IP./browser/update saves the proxy with it./browser/open returns the ws address for Playwright or Puppeteer./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
puppeteer-core.For the Python examples, install requests and Playwright. The version is pinned to the one we tested:
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:
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:
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:
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:
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:
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()/browser/closeEach 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:
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
/browser/open returns. The browser kept running after browser.close() and browser.disconnect(), which is why the samples close the profile through the API.Tips for Automated Runs
/checkagent or from the page itself./browser/close when a run ends, rather than relying on the automation library to do it.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
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.
No credit card required · 4.3 / 5 on Trustpilot ★★★★★ · 1,200+ businesses
Narmin Kamilsoy
Contributing author sharing insights and stories on our blog.