GoLogin API: Profiles Driven From Code on a Mobile Proxy

GoLogin has two API surfaces: a cloud REST API that manages profiles and a local endpoint, started by the gologin package, that launches the Orbita browser and returns a debugger URL. Together they let a script own a browser identity completely. This page shows how to point a GoLogin profile at a Mobile Proxies US line, start it from Node or Python, drive it with Puppeteer or Playwright, and sequence the line's rotation around sessions. GoLogin is the second profile browser we recommend; the first, Undetectable.io, has its own page.

Tokens and the two endpoints

The cloud API at api.gologin.com takes a developer token generated in the GoLogin app under settings. It creates, lists, updates and deletes profiles and sets their proxy. The local side is the gologin npm package (or the Python port), which downloads Orbita, applies the profile and exposes a websocket URL for CDP. The token is used by both.

Keep the GoLogin token and the Mobile Proxies US API key in the same secret store with the same rotation discipline. Both are account-wide. Neither should appear in a repository, a Dockerfile layer or a CI log.

Creating a profile with the line as proxy

A profile create call takes a JSON body with os, navigator settings and a proxy object. The proxy object has mode (http or socks5), host, port, username and password. Fill it from the line's record in GET /proxies/my so the values are never typed by hand; authentication_user holds username and password joined by a colon. For the geolocation and timezone fields choose the mode that derives them from the proxy IP; the carrier address places the profile in the right state, and the metro is right on T-Mobile and usually right on AT&T.

Name the profile after the licence uuid. Later, when the API lists your lines and GoLogin lists your profiles, the join is a string match.

import os, requests
BASE = "https://cp.mobileproxiesus.com/backend/api_v1"
H = {"x-api-key": os.environ["MPUS_API_KEY"]}
GL = gologin_headers()   # your developer token, sent the way GoLogin's own API docs specify
line = next(l for l in requests.get(f"{BASE}/proxies/my", headers=H, timeout=15).json()["proxyList"]
            if l["uuid"] == UUID)
user, password = line["authentication_user"].split(":", 1)
body = {
  "name": f"mpus-{line['uuid']}",
  "os": "win",
  "proxy": {"mode": "http", "host": line["host"], "port": line["http_port"],
            "username": user, "password": password},
  "navigator": {"language": "en-US", "resolution": "1920x1080"},
  "timezone": {"enabled": True, "fillBasedOnIp": True},
  "geolocation": {"mode": "prompt", "fillBasedOnIp": True}
}
profile_id = requests.post("https://api.gologin.com/browser", headers=GL, json=body).json()["id"]

Starting Orbita and connecting Puppeteer

The gologin package's start method launches Orbita with the profile applied and returns a websocket URL. Puppeteer connects with puppeteer.connect and browserWSEndpoint. From there the browser behaves like any Puppeteer browser, except its fingerprint is the profile's and its traffic leaves through the line.

First action in every session: load an IP echo and compare with ip from GET /proxy/status. If they differ, stop; the profile is not using the proxy and continuing would burn the identity.

// Node
const puppeteer = require('puppeteer-core');
const GoLogin = require('gologin');
const gl = new GoLogin({ token: process.env.GOLOGIN_TOKEN, profile_id: PROFILE_ID });
const { wsUrl } = await gl.start();
const browser = await puppeteer.connect({ browserWSEndpoint: wsUrl, ignoreHTTPSErrors: true });
const page = await browser.newPage();
await page.goto('https://api.ipify.org');
const seen = await page.evaluate(() => document.body.innerText.trim());
if (seen !== EXPECTED_EXIT_IP) throw new Error('profile is not on the line');
// ... work ...
await browser.close();
await gl.stop();

Headless and server runs

Orbita can run headless, but many sites treat headless signals as a negative and the point of a profile browser is to look ordinary. The reliable server setup is a Linux VM with Xvfb or a lightweight desktop, Orbita running with a display, and your script connecting over CDP. GoLogin also offers cloud-run profiles; those exit through GoLogin's infrastructure unless the profile has a proxy set, so set the line on the profile either way.

Resource planning: one Orbita instance is roughly one Chrome instance. Size the VM by the number of concurrent profiles, not by the number of lines; lines are cheap in compute terms because they live on our hardware.

Rotating the line around sessions

Rotate with the profile stopped. Sequence: stop Orbita, GET the line's rotation_link, poll /proxy/status until ip changes, start Orbita, verify, run. A rotation during a session resets the browser's connections and produces an address change mid-session, which is the single most suspicious thing a logged-in session can do.

Decide the rotation policy per profile and record it. Long-lived accounts: keep the address; a real handset on T-Mobile in Houston holds its address for hours. Independent checks: new address per check, within the line's min_time_change_ip. Either way, log the exit IP with the session id.

async function rotateLine(line) {
  const status = 'https://cp.mobileproxiesus.com/backend/api_v1/proxy/status?license=' + line.uuid;
  const ip = async () => (await (await fetch(status)).json()).ip;
  const before = await ip();
  const r = await fetch(line.rotation_link);
  if (r.status === 400) throw new Error((await r.json()).message);
  for (let i = 0; i < 30; i++) {
    await new Promise(res => setTimeout(res, 3000));
    const now = await ip();
    if (now && now !== before) return now;
  }
  throw new Error('rotation did not land');
}

Updating the proxy after a move or a login change

If you move the line to another metro (free, remaining time kept) the licence uuid and the login stay, but the host and ports can change because the line lands on another server, so the profile must be updated with a PUT on its proxy fields. If you change the line's login, same thing. A small sync job that reads GET /proxies/my, compares with the GoLogin profile list by name, and PUTs any difference keeps the two sides consistent without anyone remembering to do it.

After a move, also let the profile re-derive timezone and geolocation from the new IP, or set them explicitly. A Chicago fingerprint on a Miami address is the kind of mismatch that gets noticed.

Frequently asked