---
title: "Start a new browser session"
method: POST
path: "/v1/sessions/start"
---

# Start a new browser session

`POST /v1/sessions/start`

Creates a new browser session with the specified configuration. Returns a session ID used for all subsequent operations.

## Headers

- `x-stream-response` 'true' | 'false' — Whether to stream the response via SSE

## Request body

- SessionStartRequest
  - `modelName` string, required — Model name to use for AI operations
  - `domSettleTimeoutMs` number — Timeout in ms to wait for DOM to settle
  - `verbose` 0 | 1 | 2 — Logging verbosity level (0=quiet, 1=normal, 2=debug)
  - `systemPrompt` string — Custom system prompt for AI operations
  - `browserbaseSessionCreateParams` BrowserbaseSessionCreateParams
    - `projectId` string — Deprecated. Browserbase API keys are now project-scoped, so this field is no longer required.
    - `browserSettings` BrowserbaseBrowserSettings
      - `advancedStealth` boolean
      - `blockAds` boolean
      - `captchaImageSelector` string
      - `captchaInputSelector` string
      - `context` BrowserbaseContext
        - `id` string, required
        - `persist` boolean
      - `extensionId` string
      - `fingerprint` BrowserbaseFingerprint
        - `browsers` string[]
        - `devices` string[]
        - `httpVersion` '1' | '2'
        - `locales` string[]
        - `operatingSystems` string[]
        - `screen` BrowserbaseFingerprintScreen
          - `maxHeight` number
          - `maxWidth` number
          - `minHeight` number
          - `minWidth` number
      - `logSession` boolean
      - `os` 'windows' | 'mac' | 'linux' | 'mobile' | 'tablet'
      - `recordSession` boolean
      - `solveCaptchas` boolean
      - `verified` boolean
      - `viewport` BrowserbaseViewport
        - `width` number
        - `height` number
    - `extensionId` string
    - `keepAlive` boolean
    - `proxies` union
      - boolean
      - ProxyConfig[]
        - union
          - object
            - `type` 'browserbase', required
            - `domainPattern` string
            - `geolocation` BrowserbaseProxyGeolocation
              - …
          - object
            - `type` 'external', required
            - `server` string, required
            - `domainPattern` string
            - `username` string
            - `password` string
    - `region` 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1'
    - `timeout` number
    - `userMetadata` object
  - `browser` BrowserConfig
    - `type` 'local' | 'browserbase' — Browser type to use
    - `cdpUrl` string — Chrome DevTools Protocol URL for connecting to existing browser
    - `launchOptions` LocalBrowserLaunchOptions
      - `args` string[]
      - `executablePath` string
      - `port` number
      - `userDataDir` string
      - `preserveUserDataDir` boolean
      - `headless` boolean
      - `devtools` boolean
      - `chromiumSandbox` boolean
      - `ignoreDefaultArgs` union
        - boolean
        - string[]
      - `proxy` object
        - `server` string, required
        - `bypass` string
        - `username` string
        - `password` string
      - `locale` string
      - `viewport` object
        - `width` number, required
        - `height` number, required
      - `deviceScaleFactor` number
      - `hasTouch` boolean
      - `ignoreHTTPSErrors` boolean
      - `cdpUrl` string
      - `cdpHeaders` object
      - `connectTimeoutMs` number
      - `downloadsPath` string
      - `acceptDownloads` boolean
  - `selfHeal` boolean — Enable self-healing for failed actions
  - `browserbaseSessionID` string — Existing Browserbase session ID to resume
  - `experimental` boolean
  - `waitForCaptchaSolves` boolean — Wait for captcha solves (deprecated, v2 only)
  - `actTimeoutMs` number — Timeout in ms for act operations (deprecated, v2 only)

## Response `200`

Default Response

- SessionStartResponse
  - `success` boolean, required — Indicates whether the request was successful
  - `data` SessionStartResultOutput, required
    - `sessionId` string, required — Unique Browserbase session identifier
    - `cdpUrl` string, nullable — CDP WebSocket URL for connecting to the Browserbase cloud browser (present when available)
    - `available` boolean, required

---

[API](https://skmtc.dev/stainless-api/apis/stagehand-api.md) · [All operations](https://skmtc.dev/stainless-api/apis/stagehand-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stainless-api/stagehand-api/revisions/cdfae2ecae51/schema)