> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Parameters

> Learn about the parameters that can be used to configure Hyperbrowser sessions

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](https://hyperbrowser.ai/docs/api-reference/create-new-session.md) for full REST details.

> [!TIP]
>
> Proxy usage and CAPTCHA solving require a paid plan.

> [!NOTE]
>
> 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:**
>
> ```python Python 1.0+ theme={null}
> # Python SDK
> {"use_proxy": True, "proxy_country": "US"}
> ```
>
> ```python Python (legacy) theme={null}
> # Python SDK
> from hyperbrowser.models import CreateSessionParams
>
> CreateSessionParams(
>     use_proxy=True,
>     proxy_country="US",
> )
> ```

## Session Parameters

**enableWebMcp** `boolean` (default: false)

Enable discovery and invocation of tools exposed by pages through [WebMCP](https://hyperbrowser.ai/docs/sessions/webmcp.md). 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.

**credentials** `(string | \{ secret: string \} | \{ vault: string \} | \{ onePassword: string \})[]`

Secrets the session may [fill](https://hyperbrowser.ai/docs/sessions/credentials.md) 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](https://hyperbrowser.ai/docs/sessions/credentials.md#fill-from-1password) 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.

**webBotAuth** `boolean | object` (default: false)

Sign the session's requests with [Web Bot Auth](https://hyperbrowser.ai/docs/sessions/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](mailto: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`.

**useUltraStealth** `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](mailto:info@hyperbrowser.ai) to get access.

**useStealth** `boolean` (default: false)

When `true`, launches the session with standard stealth techniques to reduce bot detection.

**useProxy** `boolean` (default: false)

When `true`, the session will be launched with a proxy.

**proxyServer** `string`

Custom proxy server host (used only when `useProxy` is `true`). **Enterprise plan only.** Contact [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai) to get access.

**proxyServerUsername** `string`

Username for authenticating with the custom proxy server. **Enterprise plan only.**

**proxyServerPassword** `string`

Password for authenticating with the custom proxy server. **Enterprise plan only.**

**proxyCountry** `string` (default: US)

Country for proxy location (ISO 3166-1 alpha-2 code, e.g., `"US"`, `"GB"`, `"CA"`).
Check [here](https://hyperbrowser.ai/docs/api-reference/create-new-session.md#body-proxy-country) for the full list of supported countries.

**proxyState** `string`

Optional state code for proxies to US states. Is mutually exclusive with proxyCity. Takes in two letter state code.
Check [here](https://hyperbrowser.ai/docs/api-reference/create-new-session.md#body-proxy-state) for the full list of supported states.

**proxyCity** `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.

**proxyRoutes** `array[object]`

Choose, per host, whether the session's traffic goes through its proxy or straight out with [proxy routes](https://hyperbrowser.ai/docs/sessions/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](mailto:info@hyperbrowser.ai) to get access. Only supported when creating a session. In Python, use `proxy_routes`.

**region** `string`

Region to run the browser session in.
Check [here](https://hyperbrowser.ai/docs/api-reference/create-new-session.md#body-region) for the full list of supported regions.
The `asia-south` region is only available on Enterprise and Select plans. [Get in touch](https://calendly.com/shri-hyperbrowser/demo) to learn more.

**screen** `object`

Screen resolution to emulate. Properties:

* `width` (number, default `1280`)
* `height` (number, default `720`)

**solveCaptchas** `boolean` (default: false)

When `true`, the session will attempt to automatically solve CAPTCHAs.

**solverType** `"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`.

**adblock** `boolean` (default: false)

Block advertisements during the session.

**trackers** `boolean` (default: false)

Block trackers and other privacy-invasive technologies during the session.

**annoyances** `boolean` (default: false)

Block common annoyances like pop-ups and overlays.

**acceptCookies** `boolean` (default: false)

Automatically accept cookies on visited sites.

**enableWebRecording** `boolean` (default: true)

Enable web recording using rrweb.

**enableVideoWebRecording** `boolean` (default: false)

Enable mp4 video recording which captures the entire screen.

**profile** `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

**staticIpId** `string`

Static IP ID to use for the session. Check the [Static IPs](https://hyperbrowser.ai/docs/sessions/static-ips.md) page for more information.

**saveDownloads** `boolean` (default: false)

Save downloads to the session. Check the [Downloads](https://hyperbrowser.ai/docs/sessions/downloads.md) page for more information.

**extensionIds** `array`

Array of extension IDs to load. Check the [Extensions](https://hyperbrowser.ai/docs/sessions/extensions.md) page for more information.

**urlBlocklist** `array`

URLs to block during the session.

**imageCaptchaParams** `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.

**timeoutMinutes** `number`

Session timeout in minutes. Overrides your default team timeout from [Settings](https://app.hyperbrowser.ai/settings).

**enableWindowManager** `boolean` (default: false)

Enable window manager to manage browser windows and tabs.

**enableWindowManagerTaskbar** `boolean` (default: false)

Enable window manager taskbar to manage browser windows and tabs.

**viewOnlyLiveView** `boolean` (default: false)

Enable read-only Live View which disables user interactions.

**disablePasswordManager** `boolean` (default: false)

Disable the browser password manager popup on logins.

**enableAlwaysOpenPdfExternally** `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.