Skip to main content
POST
/
v1
/
sessions
/
start
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: 'gpt-4o' });

console.log(response.data);
{
  "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

Browserbase project ID

x-model-api-key
string
header
required

API key for the AI model provider (OpenAI, Anthropic, etc.)

Headers

x-stream-response
enum<string>

Whether to stream the response via SSE

Available options:
true,
false
Example:

"true"

x-sent-at
string<date-time>

ISO timestamp when request was sent

Example:

"2025-01-15T10:30:00Z"

Body

application/json
modelName
string
required

Model name to use for AI operations

Example:

"gpt-4o"

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
browser
object
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