Start a new browser session

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

post/v1/sessions/start

Request

  • Base URL: https://api.stagehand.browserbase.com
  • URL: https://api.stagehand.browserbase.com/v1/sessions/start
  • Auth: API key in header x-bb-api-key and API key in header x-bb-project-id

Headers

x-stream-response'true' | 'false'

Whether to stream the response via SSE

Example:true

Request body

modelNamestring required

Model name to use for AI operations

domSettleTimeoutMsnumber

Timeout in ms to wait for DOM to settle

verbose0 | 1 | 2

Logging verbosity level (0=quiet, 1=normal, 2=debug)

systemPromptstring

Custom system prompt for AI operations

selfHealboolean

Enable self-healing for failed actions

browserbaseSessionIDstring

Existing Browserbase session ID to resume

experimentalboolean
waitForCaptchaSolvesboolean

Wait for captcha solves (deprecated, v2 only)

actTimeoutMsnumber

Timeout in ms for act operations (deprecated, v2 only)

Example request

{
  "modelName": "openai/gpt-5.4-mini",
  "domSettleTimeoutMs": 5000,
  "verbose": 1,
  "browser": {
    "type": "local",
    "cdpUrl": "ws://localhost:9222"
  },
  "selfHeal": true
}

Response

Default Response

successboolean required

Indicates whether the request was successful

Example response

{
  "data": {
    "sessionId": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
    "cdpUrl": "wss://connect.browserbase.com/?signingKey=abc123"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.