Control Browser Profiles With a Local API: Selenium, Puppeteer and Playwright Examples

How does it work? #

The local API is a small web service that runs on your own computer, alongside the ADSSPEED app. You call it from a script to open and close profiles, and it hands back the ports that let your automation tool attach to the profile's browser.

Because the tool attaches to the profile's own browser, your script runs inside that profile: its cookies, its login, its proxy and its device settings.

Before you start #

1. Open ADSSPEED and sign in. The API runs with the app, so closing the app stops it.
2. In version 2.9.220 the API is off by default. Open Settings → API & Integrations and switch on the local API. Newer builds switch it on at startup.
3. On the same page, note the port (19555 by default) and copy the API key. Pressing "change key" makes every script using the old key stop working.
4. Check that it answers. This call needs no key:

import requests
print(requests.get("http://127.0.0.1:19555/status").json())

A healthy reply looks like {"code": 0, "data": {"version": "...", "ready": true, "api": "v1"}, "msg": "success"}. The version field tells you which documentation to read.

Open a profile in five lines #

import requests
KEY = "API_KEY"
r = requests.get("http://127.0.0.1:19555/api/v1/browser/start",
                 params={"profile_id": 1}, headers={"X-API-Key": KEY}, timeout=120).json()
print(r["data"]["ws"])   # the addresses your tool attaches to

profile_id is the profile's number in the app (1, 2, 3 and so on). The reply contains data.ws.selenium and data.ws.puppeteer, which the next sections use.

Attach Selenium (Python) #

import requests
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

BASE, KEY = "http://127.0.0.1:19555", "API_KEY"
r = requests.get(f"{BASE}/api/v1/browser/start", params={"profile_id": 1},
                 headers={"X-API-Key": KEY}, timeout=120).json()
if r["code"] != 0:
    raise SystemExit(r["msg"])

opts = Options()
opts.add_experimental_option("debuggerAddress", r["data"]["ws"]["selenium"])
driver = webdriver.Chrome(options=opts)   # attaches to the running browser
driver.get("https://ip.me/")
print(driver.title)

Selenium needs a chromedriver with the same version as the profile's browser. To read that version, open http://127.0.0.1:<debug_port>/json/version and look at the Browser field. Selenium's automatic driver management may look at a Chrome installed on your computer instead, so if the versions don't match, pass the driver path yourself with Service(executable_path=...) from selenium.webdriver.chrome.service.

The debuggerAddress option takes a host:port address, which is exactly what data.ws.selenium contains.

Attach Puppeteer (Node.js) #

// npm i puppeteer-core   ·   Node 18+, save as .mjs
import puppeteer from "puppeteer-core";

const BASE = "http://127.0.0.1:19555", KEY = "API_KEY";
const r = await (await fetch(`${BASE}/api/v1/browser/start?profile_id=1`,
                             { headers: { "X-API-Key": KEY } })).json();
if (r.code !== 0) throw new Error(r.msg);

// defaultViewport: null keeps the profile's own window size
const browser = await puppeteer.connect({ browserWSEndpoint: r.data.ws.puppeteer, defaultViewport: null });
const [page] = await browser.pages();
await page.goto("https://ip.me/");
console.log(await page.title());
browser.disconnect();   // detach; does NOT close the profile's browser

Attach Playwright (Python) #

# pip install playwright requests
import requests
from playwright.sync_api import sync_playwright

BASE, KEY = "http://127.0.0.1:19555", "API_KEY"
r = requests.get(f"{BASE}/api/v1/browser/start", params={"profile_id": 1},
                 headers={"X-API-Key": KEY}, timeout=120).json()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(r["data"]["ws"]["puppeteer"])
    ctx = browser.contexts[0]                       # the profile's own context
    page = ctx.pages[0] if ctx.pages else ctx.new_page()
    page.goto("https://ip.me/")
    print(page.title())

Always reuse the profile's existing context and tab. Creating a new one starts a clean session without the profile's cookies, which is the most common reason for a blank page and a lost login. Playwright's documentation also notes that connecting over CDP works only with Chromium-based browsers and has lower fidelity than its own protocol connection.

Close the profile #

When your script is done, detach the tool (driver.quit() closes Selenium's session, browser.disconnect() detaches Puppeteer), then close the profile itself:

requests.get(f"{BASE}/api/v1/browser/stop", params={"profile_id": 1}, headers={"X-API-Key": KEY})

Authentication and the response format #

Every command except /status needs the key. Send it in a header (recommended) or as a parameter:

X-API-Key: ads-1a2b3c4d
/api/v1/profile/list?key=ads-1a2b3c4d

Every reply has the same shape, {code, data, msg}. Check code before you read data.

Newer builds also return 403 when the app isn't signed in yet.

Open many profiles safely #

Opening a profile is a heavy command: at most one per second, otherwise you get 429. A first open with a proxy can take several seconds, so use a generous timeout (the docs advise at least 90 seconds). Once profiles are open you can drive them in parallel, with one driver or browser connection per profile. Wrap each profile in try/finally so it always closes:

import time, requests
BASE, KEY = "http://127.0.0.1:19555", "API_KEY"
H = {"X-API-Key": KEY}

def call(path, **params):
    r = requests.get(f"{BASE}{path}", params=params, headers=H, timeout=120).json()
    if r["code"] != 0:
        raise RuntimeError(f'{path}: {r["code"]} {r["msg"]}')
    return r["data"]

for pid in (1, 2, 3):
    data = call("/api/v1/browser/start", profile_id=pid)
    try:
        ...   # attach your tool to data["ws"]["selenium"] or data["ws"]["puppeteer"], do the work
    finally:
        call("/api/v1/browser/stop", profile_id=pid)
    time.sleep(1.1)    # heavy commands: one per second at most

Common problems #

What the API can and can't do #

• It does what the app allows on your plan, no more. Profiles created through the API count toward your plan like any other.
• Secrets stay hidden. Proxy passwords are always returned as ***.
• Fingerprints are built by the app for each profile, so the API doesn't edit them. For a custom setup, create a sample configuration in the app and pick it when you create profiles.
• Phone profiles aren't in the API yet. It covers browser profiles.

In 2.9.220 the API has 27 commands in six groups: profile control, profile information, profile operations, proxies (including your own mobile proxies from a USB modem), extensions, and system status. Newer builds add scripts, campaigns, schedules, cookies and more. The full list, with a Postman collection, is in the API documentation.

Keep the key private #

The API listens only on 127.0.0.1, so other computers on your network can't reach it. But other programs on your machine, including web pages open in your browser, can call it if they know the key. Don't paste the key into external services, bots or public repositories, and press "change key" the moment you suspect a leak.