Skip to main content
This page documents the parameters that can be used to configure Hyperbrowser sessions. These parameters are shared across New Session, Scrape, Crawl, Extract, and Agent Tasks. You can view the Sessions API Reference at Sessions API Reference for full REST details.
Proxy usage and CAPTCHA solving require a paid plan.
When using the Python SDK, all session parameters are in snake_case (e.g., use_proxy), whereas in JavaScript/TypeScript they use camelCase (e.g., useProxy). Example:

​
Session Parameters

​
boolean
default:false
Enable discovery and invocation of tools exposed by pages through WebMCP. Set this when creating a session; it cannot be enabled on an existing session. In Python, use enable_web_mcp. Leaving it unset keeps WebMCP disabled.
​
(string | { secret: string } | { vault: string } | { onePassword: string })[]
Secrets the session may fill into login forms, up to 20: a secret’s name, { secret: name }, { vault: name } for the secrets a vault’s entries point at, or { onePassword: name } for an op_token secret that 1Password fills read with. They can only be attached when the session is created, and each secret needs allowed origins before it can be filled. Attaching them needs the secrets.use scope, runs the session on a Firecracker browser, and turns off Chrome’s password manager. Applies only when creating a session directly, not to Scrape, Crawl, Extract or Agent tasks.
​
boolean | object
default:false
Sign the session’s requests with Web Bot Auth so websites can verify that they come from Hyperbrowser. Pass { "onlyDomains": ["example.com"] } to sign only requests to those hostnames and their subdomains (up to 50). Available on request: contact info@hyperbrowser.ai to get access. Supported for new sessions and agent tasks, but not for scrape, crawl, or extract, and cannot be combined with useUltraStealth or startFromSnapshot. In Python, use web_bot_auth and only_domains.
​
boolean
default:false
When true, launches the session with advanced stealth techniques to reduce bot detection. This is only available on enterprise plans. Please contact us at info@hyperbrowser.ai to get access.
​
boolean
default:false
When true, launches the session with standard stealth techniques to reduce bot detection.
​
boolean
default:false
When true, the session will be launched with a proxy.
​
string
Custom proxy server host (used only when useProxy is true). Enterprise plan only. Contact info@hyperbrowser.ai to get access.
​
string
Username for authenticating with the custom proxy server. Enterprise plan only.
​
string
Password for authenticating with the custom proxy server. Enterprise plan only.
​
string
default:"US"
Country for proxy location (ISO 3166-1 alpha-2 code, e.g., "US", "GB", "CA"). Check here for the full list of supported countries.
​
string
Optional state code for proxies to US states. Is mutually exclusive with proxyCity. Takes in two letter state code. Check here for the full list of supported states.
​
string
Desired City. Is mutually exclusive with proxyState. Some cities might not be supported, so before using a new city, we recommend trying it out.
​
array[object]
Choose, per host, whether the session’s traffic goes through its proxy or straight out with proxy routes. Each route has a match (a hostname, *.example.com, or *, or a list of them) and a proxy ("direct" or "default"). The first route that matches a host decides; hosts that no route matches use the proxy. Requires useProxy. Available on request: contact info@hyperbrowser.ai to get access. Only supported when creating a session. In Python, use proxy_routes.
​
string
Region to run the browser session in. Check here for the full list of supported regions. The asia-south region is only available on Enterprise and Select plans. Get in touch to learn more.
​
object
Screen resolution to emulate. Properties:
  • width (number, default 1280)
  • height (number, default 720)
​
boolean
default:false
When true, the session will attempt to automatically solve CAPTCHAs.
​
"visual"
Optional CAPTCHA solver mode. Set to "visual" to use the visual reCAPTCHA solver when automatic CAPTCHA solving is enabled. In the Python SDK, use solver_type.
​
boolean
default:false
Block advertisements during the session.
​
boolean
default:false
Block trackers and other privacy-invasive technologies during the session.
​
boolean
default:false
Block common annoyances like pop-ups and overlays.
​
boolean
default:false
Automatically accept cookies on visited sites.
​
boolean
default:true
Enable web recording using rrweb.
​
boolean
default:false
Enable mp4 video recording which captures the entire screen.
​
object
Reuse browser state across sessions. Properties:
  • id (string): Profile ID to use for the session
  • persistChanges (boolean, default false): Persist changes back to the profile on session close
​
string
Static IP ID to use for the session. Check the Static IPs page for more information.
​
boolean
default:false
Save downloads to the session. Check the Downloads page for more information.
​
array
Array of extension IDs to load. Check the Extensions page for more information.
​
array
URLs to block during the session.
​
array[object]
Array of objects for customizing image captcha solving. Each object supports:
  • imageSelector (string): CSS selector for the captcha image element.
  • inputSelector (string): CSS selector for the input field where the captcha answer should be entered.
​
number
Session timeout in minutes. Overrides your default team timeout from Settings.
​
boolean
default:false
Enable window manager to manage browser windows and tabs.
​
boolean
default:false
Enable window manager taskbar to manage browser windows and tabs.
​
boolean
default:false
Enable read-only Live View which disables user interactions.
​
boolean
default:false
Disable the browser password manager popup on logins.
​
boolean
default:false
Always open PDFs externally instead of in browser. This will download the PDF instead of opening it in the browser PDF viewer.