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

JavaScript

JavaScript

import Stagehand from 'stagehand-sdk';

const client = new Stagehand({
  browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
  browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
  modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
});

const response = await client.sessions.start({ modelName: 'openai/gpt-5.4-mini' });

console.log(response.data);

200

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

Authorizations

x-bb-api-key · string · header · required

Browserbase API key for authentication

x-bb-project-id · string · header · required

Deprecated. Browserbase API keys are now project-scoped, so this header is no longer required.

Headers

x-stream-response · enum<string>

Whether to stream the response via SSE

Available options: true, false

Example:

"true"

Body

application/json

modelName · string · required

Model name to use for AI operations

Example:

"openai/gpt-5.4-mini"

domSettleTimeoutMs · number

Timeout in ms to wait for DOM to settle

Example:

5000

verbose · enum<number>

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

Available options: 0, 1, 2

Example:

1

systemPrompt · string

Custom system prompt for AI operations

browserbaseSessionCreateParams · object

Show child attributes

browser · object

Show child attributes

selfHeal · boolean

Enable self-healing for failed actions

Example:

true

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 - application/json

Default Response

success · boolean · required

Indicates whether the request was successful

data · object · required

Show child attributes