> ## 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.

# Configuring Sessions

> Learn how to create and configure Hyperbrowser sessions

Sessions are isolated browser instances running in the cloud that you can control programmatically. Each session gives you a WebSocket endpoint to connect with Playwright, Puppeteer, or any CDP-compatible tool.

## Quick Start

Create a session with default settings:

<CodeGroup>
  ```typescript Node.js theme={null}
  import { Hyperbrowser } from "@hyperbrowser/sdk";
  import { config } from "dotenv";

  config();

  const client = new Hyperbrowser({
    apiKey: process.env.HYPERBROWSER_API_KEY,
  });

  async function main() {
    const session = await client.sessions.create();

    console.log("Session ID:", session.id);
    console.log("WebSocket:", session.wsEndpoint);
    console.log("Live Url:", session.liveUrl);
  }

  main();
  ```

  ```python Python theme={null}
  from hyperbrowser import Hyperbrowser
  import os
  from dotenv import load_dotenv

  load_dotenv()

  client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

  session = client.sessions.create()

  print(f"Session ID: {session.id}")
  print(f"WebSocket: {session.ws_endpoint}")
  print(f"Live Url: {session.live_url}")
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

You can view the live session at the live url link provided in the response.

Active sessions can be also viewed and managed in the [Sessions](https://app.hyperbrowser.ai/features/sessions) page in the dashboard.

<Tip>
  Remember to stop the sessions when are you are done with them.
  See the [Session Lifecycle](/sessions/lifecycle) guide for more information on managing sessions through code.
</Tip>

## Configuration Options

Customize your session with these options:

<CodeGroup>
  ```typescript Node.js theme={null}
  const session = await client.sessions.create({
    acceptCookies: true,
    useStealth: true,
    useUltraStealth: false,
    useProxy: true,
    screen: {
      width: 1920,
      height: 1080,
    },
    timeoutMinutes: 30,
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams, ScreenConfig

  session = client.sessions.create(
      params=CreateSessionParams(
          accept_cookies=True,
          use_stealth=True,
          use_ultra_stealth=False,
          use_proxy=True,
          screen=ScreenConfig(width=1920, height=1080),
          timeout_minutes=30
      )
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "acceptCookies": true,
      "useStealth": true,
      "useUltraStealth": false,
      "useProxy": true,
      "screen": {
        "width": 1920,
        "height": 1080
      },
      "timeoutMinutes": 30
    }'
  ```
</CodeGroup>

### Common Configuration Options

<ParamField path="acceptCookies" type="boolean" default={false}>
  Automatically accept cookies on pages that are visited in the session
</ParamField>

<ParamField path="useStealth" type="boolean" default={false}>
  Enable standard stealth mode to evade basic bot detection
</ParamField>

<ParamField path="useUltraStealth" type="boolean" default={false}>
  Enable advanced stealth mode for maximum bot detection evasion (reach out to us at [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai) to get access)
</ParamField>

<ParamField path="useProxy" type="boolean" default={false}>
  Route traffic through a proxy (see [Proxy Guide](/sessions/proxy) for configuration)
</ParamField>

<ParamField path="screen" type="object">
  Screen dimensions with `width` and `height` (default: 1280x720)
</ParamField>

<ParamField path="timeoutMinutes" type="number">
  Session timeout in minutes (min: 1, max: 720)
</ParamField>

<Note>
  This shows the most commonly used options. For the complete list of configuration parameters including proxy settings, CAPTCHA solving, recordings, profiles, extensions, and more, see:

  * [Python SDK Documentation](/sdks/python#create-session) - Full parameter reference
  * [Node.js SDK Documentation](/sdks/node#create-session) - Full parameter reference
  * [API Reference](/api-reference/create-new-session) - Complete REST API documentation
</Note>

## Session Response

The API returns a session object with these properties:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sessionUrl": "https://...",
  "wsEndpoint": "wss://...",
  "liveUrl": "https://...",
  "computerActionEndpoint": "https://...",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  ... // other properties
}
```

<Note>
  To see the complete list of properties, see the [API Reference](/api-reference/create-new-session).
</Note>

<ResponseField name="id" type="string">
  Unique session identifier
</ResponseField>

<ResponseField name="wsEndpoint" type="string">
  WebSocket URL for browser automation
</ResponseField>

<ResponseField name="liveUrl" type="string">
  URL to view the session in real-time
</ResponseField>

<ResponseField name="sessionUrl" type="string">
  URL to view the session page in the dashboard
</ResponseField>

<ResponseField name="computerActionEndpoint" type="string">
  URL to send computer actions to the session
</ResponseField>

<ResponseField name="status" type="string">
  Current status (`active`, `closed`, or `error`)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp
</ResponseField>

<ResponseField name="launchState" type="object | null">
  The parameters that were used to launch the session.
  See the [API Reference](/api-reference/create-new-session#response-launch-state) for more details.
</ResponseField>

<ResponseField name="creditsUsed" type="number | null">
  Credits used by the session
</ResponseField>

## Stealth Mode

Bypass bot detection with stealth features:

<CodeGroup>
  ```typescript Node.js theme={null}
  // Standard stealth (recommended for most sites)
  const session = await client.sessions.create({
    useStealth: true,
  });

  // Ultra stealth (for challenging sites)
  const session = await client.sessions.create({
    useUltraStealth: true,
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams

  # Standard stealth (recommended for most sites)
  session = client.sessions.create(
      params=CreateSessionParams(use_stealth=True)
  )

  # Ultra stealth (for challenging sites)
  session = client.sessions.create(
      params=CreateSessionParams(use_ultra_stealth=True)
  )
  ```

  ```bash cURL theme={null}
  # Standard stealth
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"useStealth": true}'

  # Ultra stealth
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"useUltraStealth": true}'
  ```
</CodeGroup>

<Tip>
  Ultra stealth is only available on enterprise plans. Reach out to us at [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai) to learn more.
</Tip>

## Proxies

Route sessions through proxies for geo-targeting or additional anonymity:

<CodeGroup>
  ```typescript Node.js theme={null}
  const session = await client.sessions.create({
    useProxy: true,
    proxyCountry: "US",
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams

  session = client.sessions.create(
      params=CreateSessionParams(
          use_proxy=True,
          proxy_country="US"
      )
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "useProxy": true,
      "proxyCountry": "US"
    }'
  ```
</CodeGroup>

<Note>
  See the [Proxy Guide](/sessions/proxy) for advanced proxy configuration including states, cities, and custom proxy servers.
</Note>

## Session Timeout

Sessions automatically close after a certain amount of time based on your team's default timeout setting. You can change the default timeout on the [Settings page](https://app.hyperbrowser.ai/settings). You can also configure the timeout per session during session creation:

<CodeGroup>
  ```typescript Node.js theme={null}
  const session = await client.sessions.create({
    timeoutMinutes: 60, // 1 hour
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams

  session = client.sessions.create(
      params=CreateSessionParams(timeout_minutes=60)
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"timeoutMinutes": 60}'
  ```
</CodeGroup>

## Custom Screen Size

Set custom screen dimensions for specific testing scenarios:

<CodeGroup>
  ```typescript Node.js theme={null}
  const session = await client.sessions.create({
    screen: {
      width: 1920,
      height: 1080,
    },
  });
  ```

  ```python Python theme={null}
  from hyperbrowser.models import CreateSessionParams, ScreenConfig

  session = client.sessions.create(
      params=CreateSessionParams(
          screen=ScreenConfig(width=1920, height=1080)
      )
  )
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.hyperbrowser.ai/api/session \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "screen": {
        "width": 1920,
        "height": 1080
      }
    }'
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Lifecycle Management" icon="rotate" href="/sessions/lifecycle">
    Stop, monitor, and manage active sessions
  </Card>

  <Card title="Connect with Playwright" icon="code" href="/sessions/playwright">
    Use Playwright to control your session
  </Card>

  <Card title="Connect with Puppeteer" icon="code" href="/sessions/puppeteer">
    Use Puppeteer to control your session
  </Card>

  <Card title="Stealth Mode" icon="user-secret" href="/sessions/stealth">
    Deep dive into anti-detection features
  </Card>
</CardGroup>