OS emulation
BrowserQL sessions run on Linux, so they expose a Linux fingerprint by default. Bot detection systems cross-check signals like the User-Agent, navigator.platform, UA Client Hints, GPU renderer, and media devices, and flag sessions where these don't line up. The emulationOs query parameter switches the session to a coherent operating system identity — set it to windows or macos to move off the default Linux fingerprint, or to android or ios to present a phone or tablet.
- A Browserless API token from your account dashboard
- Familiarity with BrowserQL basics
emulationOs is a URL query parameter on the endpoint. It is not a header, a launch option, or a mutation, and it behaves identically whether you call BQL over HTTP POST or WebSocket. It works on any regional endpoint, on stealth and BQL routes, on the unblock and scrape REST APIs (/unblock, /smart-scrape), and on the Agent route (/chromium/agent). On a plain route like /chromium or /chrome it is ignored rather than rejected, and the session keeps its default identity.
Emulating an OS on BQL routes
Every BQL route — /chromium/bql, /chrome/bql, and /stealth/bql — runs a stealth-hardened browser. emulationOs selects the operating system identity the session presents: pass windows or macos to apply that platform's full fingerprint stack, android or ios to present a phone or tablet, or omit it to keep the native Linux identity.
# Windows identity on /stealth/bql
curl -X POST \
'https://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=windows' \
-H 'Content-Type: application/json' \
-d '{
"query": "mutation { goto(url: \"https://example.com\") { status } }"
}'
Accepted values
| Value | Emulated identity |
|---|---|
windows | Windows / Chrome on Win64 |
macos | macOS / Chrome on Intel Mac |
linux | Native Linux identity (the default when omitted) |
android | Mobile Chrome on Android — see Android (mobile) emulation |
ios | Mobile Safari on an iPhone or iPad — see iOS (mobile and tablet) emulation |
Desktop windows, macos, and linux and mobile android and ios identities are supported. Values are case-sensitive and must match exactly. Any other value, including a typo or wrong casing like macOS, is rejected with an HTTP 400 and the session doesn't start.
What gets spoofed
When emulationOs is set, the session presents one internally consistent set of signals for the target OS:
- User-Agent (e.g.
Windows NT 10.0; Win64; x64) - UA Client Hints —
Sec-CH-UA-Platform,Sec-CH-UA-Platform-Version,getHighEntropyValues() navigator.platform—Win32,MacIntel, orLinux x86_64- GPU / WebGL renderer and CPU core count (
navigator.hardwareConcurrency) for the platform - Media devices, speech-synthesis voices, and AudioContext latency for the OS
These signals stay consistent for the session's lifetime, including across navigations and new windows.
What it doesn't change
emulationOs only sets OS-derived browser signals. What stays untouched depends on the identity.
Desktop identities
For windows, macos, and linux, emulationOs does not change:
- Timezone, locale, and
Accept-Language— these follow your proxy's location, not the emulated OS. - Screen and viewport size — set these on the client.
- WebRTC handling — applied uniformly to every stealth session.
Android emulation
emulationOs=android does set screen and viewport size: it applies a high-DPI mobile viewport (see Android (mobile) emulation). Everything else stays the same as desktop. It does not change:
- Timezone, locale, and
Accept-Language— these follow your proxy's location, not the emulated OS. - WebRTC handling — applied uniformly to every stealth session.
iOS emulation
emulationOs=ios also sets screen and viewport size from the device profile (see iOS (mobile and tablet) emulation), so screen and deviceScaleFactor are ignored. It does not change:
- Timezone, locale, and
Accept-Language— these follow your proxy's location, not the emulated OS. - WebRTC handling — applied uniformly to every stealth session.
An emulated identity served with a mismatched timezone or locale is itself a detection signal, so pair emulationOs with a region-matched proxy for a fully coherent profile.
Using with the BQL IDE
In the BQL IDE, select the Stealth browser (which uses /stealth/bql) and append emulationOs to the endpoint URL in your session settings:
https://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=macos
Without emulationOs the session keeps the native Linux identity; append &emulationOs=windows or &emulationOs=macos to switch.
Using with the WebSocket BQL route
The BQL WebSocket route speaks GraphQL over WebSocket: send { "query": "..." } JSON messages and read { "data": ... } replies (this is not CDP, so Puppeteer/Playwright clients don't apply here). Pass emulationOs in the connection URL. From Node.js with the ws package:
import WebSocket from "ws";
const TOKEN = "YOUR_API_TOKEN_HERE";
const ws = new WebSocket(
`wss://production-sfo.browserless.io/stealth/bql?token=${TOKEN}&emulationOs=windows`
);
ws.on("open", () => {
ws.send(JSON.stringify({
query: `mutation { goto(url: "https://example.com") { status } }`,
}));
});
ws.on("message", (data) => console.log(JSON.parse(data.toString())));
Combining with other BQL features
emulationOs composes with other BQL mutations:
userAgent()mutation overrides the User-Agent for the rest of the session. For a desktop Windows or macOS Chrome/Chromium User-Agent,navigator.platformand UA Client Hints are derived from it automatically to stay coherent; a Linux, mobile, or non-Chromium User-Agent is applied as-is and leaves the emulated platform and Client Hints unchanged — so keep the User-Agent consistent with the emulated OS.proxymutation adds a residential or datacenter proxy. The OS fingerprint and proxy are independent layers — match the proxy region to the emulated OS for a coherent timezone and locale.solve()mutation for CAPTCHA solving works normally on emulated sessions.
mutation {
goto(url: "https://protected-site.com") { status }
solve(wait: true) { solved }
}
The above query, sent to /stealth/bql?emulationOs=windows, runs with a full Windows identity and solves any detected CAPTCHA.
Android (mobile) emulation
Set emulationOs=android to make a BQL session present as mobile Chrome on Android instead of a desktop OS. Add emulatedDevice=<slug> to pick a specific phone, or omit it and Browserless picks a real device for you and keeps it consistent for the whole session. Android emulation runs on the Chromium and Brave stealth engines.
Enabling Android emulation
emulationOs and emulatedDevice are connection query-string parameters on the endpoint URL, not BQL mutation arguments. They work the same over HTTP POST and WebSocket on any BQL route.
BQL over HTTP POST — put the parameters on the URL and send a normal GraphQL body:
curl -X POST \
'https://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=android&emulatedDevice=galaxy-s25-ultra' \
-H 'Content-Type: application/json' \
-d '{
"query": "mutation { goto(url: \"https://example.com\") { status } title }"
}'
BQL over WebSocket:
wss://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=android&emulatedDevice=pixel-8-pro
Omit emulatedDevice and Browserless picks a device for you:
wss://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=android
The session then runs mutations as normal, exactly as it does with emulationOs=windows. The same parameters also work when connecting Puppeteer or Playwright to a stealth route.
Choosing a device
emulatedDevice takes one of the supported Android slugs — for example pixel-8-pro or galaxy-s25-ultra. See Supported mobile devices for the full list. Omitting emulatedDevice is fine: Browserless picks a real device automatically and keeps it stable across reconnects within the session.
What gets emulated
emulationOs=android shifts the whole identity to a coherent mobile persona:
- Mobile User-Agent and Client Hints — the browser reports as Chrome on Android, and the specific model is exposed through UA Client Hints.
- Phone screen size and pixel ratio — a high-DPI mobile viewport.
- Touch input — coarse-pointer and no-hover behavior.
- Portrait orientation.
- Motion sensors — accelerometer, gyroscope, and orientation.
- Mobile GPU / WebGL renderer identity, Android system fonts, mobile media devices and voices, and Android-appropriate battery and network signals.
Rules and errors
emulatedDevicerequiresemulationOs=androidorios. SendingemulatedDeviceon a stealth session without one of them returns an HTTP 400 with the message:emulatedDevice requires emulationOs=android or ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).- Device slugs are case-sensitive and matched exactly. Use them as listed (
pixel-8, notPixel-8orpixel8). - An unrecognized
emulatedDevicevalue is not an error. Browserless falls back to an automatically chosen device. emulationOsaccepts only the exact lowercase valueswindows,macos,linux,android, andios. Any other value, including wrong casing likeAndroid, returns an HTTP 400.deviceType=phoneis accepted and changes nothing on Android.deviceType=tabletreturns an HTTP 400 with the message:deviceType=tablet requires emulationOs=ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).
Limitations
- Phones only. For an iPhone or iPad, use
emulationOs=ios. - All emulated devices are modern flagship phones in portrait orientation.
iOS (mobile and tablet) emulation
Set emulationOs=ios to make a BQL session present as Safari on an iPhone. Add deviceType=tablet for an iPad, or emulatedDevice=<slug> to pick an exact model. Omit both and Browserless picks an iPhone for you and keeps it consistent for the whole session, including reconnects. iOS emulation runs on the Chromium and Brave stealth engines.
The browser underneath is Chromium with an iOS identity. It reports what an iPhone or iPad reports to the page and the network, while traits that come from the engine itself stay Chromium's (see the limitations below).
Enabling iOS emulation
emulationOs, deviceType, and emulatedDevice are connection query-string parameters on the endpoint URL, not BQL mutation arguments. They work the same over HTTP POST and WebSocket on any BQL route.
BQL over HTTP POST, pinning an iPhone model and reading navigator.platform back:
curl -X POST \
'https://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=ios&emulatedDevice=iphone-16' \
-H 'Content-Type: application/json' \
-d '{
"query": "mutation { goto(url: \"https://example.com\") { status } platform: evaluate(content: \"navigator.platform\") { value } }"
}'
Response:
{
"data": {
"goto": {
"status": 200
},
"platform": {
"value": "iPhone"
}
}
}
BQL over WebSocket, letting Browserless pick an iPad:
wss://production-sfo.browserless.io/stealth/bql?token=YOUR_API_TOKEN_HERE&emulationOs=ios&deviceType=tablet
The session then runs mutations as normal. The same parameters also work when connecting Puppeteer or Playwright to a stealth route.
Choosing a device and device type
deviceType picks the pool Browserless draws from when emulatedDevice is absent: phone (the default) or tablet. emulatedDevice names an exact model, and a named model decides the device. If you send both, they must agree. See Supported mobile devices for every iPhone and iPad slug.
An unrecognized emulatedDevice value is not an error. Browserless falls back to an automatically chosen device from the deviceType pool.
What gets emulated
emulationOs=ios shifts the whole identity to a coherent iPhone or iPad:
- Safari User-Agent for an iPhone or iPad, on every engine. On
/stealth/bql, which runs the Brave engine, the string ends with aBravetoken. - UA Client Hints are absent, as on every iOS browser: the session sends no
Sec-CH-UArequest headers, andnavigator.userAgentDataisundefined. navigator.platform—iPhoneoriPad, withnavigator.vendorset toApple Computer, Inc.- Device screen size and pixel ratio — a pixel ratio of 3 for iPhones and 2 for iPads.
- Touch input — five touch points and a coarse pointer.
- Portrait orientation.
- Apple GPU / WebGL renderer identity and four CPU cores (
navigator.hardwareConcurrency).navigator.deviceMemoryis absent, as in Safari. - WebKit-style page surface —
window.chromeis absent, and Chromium-specific APIs such as WebHID, Web Serial, and EyeDropper are hidden.
Rules and errors
emulatedDevicerequiresemulationOs=androidorios, as described for Android. Sending it without one of them returns an HTTP 400 with the message:emulatedDevice requires emulationOs=android or ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).deviceTypemust bephoneortablet. Any other value returns an HTTP 400 with the message:deviceType must be phone or tablet.deviceTypeneeds a mobileemulationOson a stealth request. Sending it with a desktop value or with none returns an HTTP 400 with the message:deviceType requires a mobile emulationOs (android|ios) on a stealth request (a /stealth/*, BQL, or /chromium/agent route).deviceType=tabletneedsemulationOs=ios. WithemulationOs=androidit returns an HTTP 400 with the message:deviceType=tablet requires emulationOs=ios on a stealth request (a /stealth/*, BQL, or /chromium/agent route).- A named iOS slug of the other kind, such as
emulatedDevice=ipad-pro-11&deviceType=phone, returns an HTTP 400 with the message:deviceType contradicts emulatedDevice. - Device slugs are case-sensitive and matched exactly. Use them as listed, in lowercase.
screenanddeviceScaleFactorare ignored, because the device profile sets both.deviceSlotbelongs to desktop personas, so sending it withemulationOs=iosreturns an HTTP 400. A valid slot number gets the message:deviceSlot requires a desktop emulationOs (windows|macos|linux) on a stealth request (a /stealth/*, BQL, or /chromium/agent route).
Limitations
- iOS emulation is Chromium with an iOS identity. Traits that come from the engine stay Chromium's: V8 error wording and stack shape, the TLS and HTTP/2 fingerprint, fonts, CSS feature support, and media codecs.
- The WebKit-style surface is applied to the page itself. Workers and cross-site iframes keep Chromium's.
- Safari's own engine (WebKit) is available separately through Playwright. See Supported browsers.
- Devices are the listed iPhone and iPad models, in portrait orientation.
FAQ & Troubleshooting
Does emulationOs work on plain (non-stealth) routes?
No. emulationOs only takes effect on stealth routes, the unblock and scrape REST APIs (/unblock, /chromium/unblock, /chrome/unblock, /smart-scrape), BQL routes, and the Agent route (/chromium/agent). On a plain route (/chromium, /chrome) it is ignored rather than rejected, so the session silently keeps its default identity. Use a /stealth route, /unblock, /smart-scrape, a /bql route, or /chromium/agent.
Can I emulate an iPhone or iPad?
Yes. Set emulationOs=ios for an iPhone, and add deviceType=tablet for an iPad. See iOS (mobile and tablet) emulation for the rules, and Supported mobile devices for the model slugs.
Can I verify what OS identity my session is reporting?
Yes. Use a JavaScript evaluate in BQL to check the exposed APIs:
mutation {
goto(url: "https://example.com") { status }
evaluate(content: "JSON.stringify({ platform: navigator.platform, ua: navigator.userAgent })")
}
With emulationOs=windows, this returns {"platform":"Win32","ua":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."}.