Browserbase

Troubleshooting

If requests fail, run zero doctor check-connector --env-name BROWSERBASE_TOKEN or zero doctor check-connector --url https://api.browserbase.com/v1/sessions --method POST

How to Use

1. Create a Session

Create a new browser session:

Write /tmp/request.json:

{
  "projectId": "<your-project-id>"
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

With timeout and keepAlive:

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "timeout": 300,
  "keepAlive": true
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

With proxy enabled (requires paid plan):

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "proxies": true
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Note: Proxies are not available on the free plan. You'll receive a 402 error if you try to use this feature without upgrading.

With specific region (us-west-2, us-east-1, eu-central-1, ap-southeast-1):

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "region": "us-west-2"
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Response includes:

• id - Session ID to use for connections
• connectUrl - WebSocket URL for Playwright/Puppeteer
• seleniumRemoteUrl - URL for Selenium connections
• signingKey - Key for HTTP connections

2. List Sessions

List all sessions with optional filters:

curl -s -X GET "https://api.browserbase.com/v1/sessions" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Filter by status (RUNNING, ERROR, TIMED_OUT, COMPLETED):

curl -s -X GET "https://api.browserbase.com/v1/sessions?status=RUNNING" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Query by user metadata:

Note: The query syntax for user metadata filtering uses single quotes: user_metadata['key']:'value'. To avoid complex shell escaping, write the query to a file and use --data-urlencode "q@filename".

Write /tmp/query.txt with content:

user_metadata['test']:'true'

Then query sessions:

curl -s -X GET -G "https://api.browserbase.com/v1/sessions" --data-urlencode "q@/tmp/query.txt" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

More examples:

Query by stagehand metadata - write /tmp/query.txt:

user_metadata['stagehand']:'true'

Query by environment - write /tmp/query.txt:

user_metadata['env']:'production'

Then run:

curl -s -X GET -G "https://api.browserbase.com/v1/sessions" --data-urlencode "q@/tmp/query.txt" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

3. Get Session Details

Get details of a specific session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

4. Update Session (Release)

Request to release a session before its timeout to avoid additional charges. Replace <your-session-id> with the actual session ID:

Write /tmp/request.json:

{
  "status": "REQUEST_RELEASE"
}

curl -s -X POST "https://api.browserbase.com/v1/sessions/<your-session-id>" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

The session status will change to COMPLETED and endedAt timestamp will be set.

5. Get Debug/Live URLs

Get live debugging URLs for a running session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/debug" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Note: Debug URLs may only be available after a browser client has connected to the session via WebSocket.

Response includes:

• debuggerUrl - Chrome DevTools debugger URL
• debuggerFullscreenUrl - Fullscreen debugger view
• wsUrl - WebSocket URL
• pages - Array of open pages with their debugger URLs

6. Get Session Logs

Retrieve logs from a session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/logs" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

7. Get Session Recording

Get the rrweb recording of a session. Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/recording" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

8. Get Session Downloads

Retrieve files downloaded during a session (returns ZIP file). Replace <your-session-id> with the actual session ID:

curl -s -X GET "https://api.browserbase.com/v1/sessions/<your-session-id>/downloads" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" --output downloads.zip

9. Upload Files to Session

Upload files to use in a browser session. Replace <your-session-id> with the actual session ID:

curl -s -X POST "https://api.browserbase.com/v1/sessions/<your-session-id>/uploads" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -F "file=@/path/to/file.pdf"

Contexts API

Contexts allow you to persist cookies, cache, and session storage across multiple browser sessions.

Create a Context

Write /tmp/request.json:

{
  "projectId": "<your-project-id>"
}

curl -s -X POST "https://api.browserbase.com/v1/contexts" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Save the returned id to use in sessions.

Get Context Details

Retrieve details of a specific context. Replace <your-context-id> with the actual context ID:

curl -s -X GET "https://api.browserbase.com/v1/contexts/<your-context-id>" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

Response includes:

• id - Context identifier
• createdAt - Creation timestamp
• updatedAt - Last update timestamp
• projectId - The Project ID linked to the context

Create Session with Context

Use an existing context to restore cookies and login state. Replace <your-context-id> with the actual context ID:

Write /tmp/request.json:

{
  "projectId": "<your-project-id>",
  "browserSettings": {
    "context": {
      "id": "<your-context-id>",
      "persist": true
    }
  }
}

curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -d @/tmp/request.json

Set persist: true to save updates back to the context after the session ends.

Delete Context

Delete a context when it's no longer needed. Replace <your-context-id> with the actual context ID:

curl -s -X DELETE "https://api.browserbase.com/v1/contexts/<your-context-id>" --header "X-BB-API-Key: $BROWSERBASE_TOKEN" -w "\nHTTP Status: %{http_code}"

Successful deletion returns HTTP 204 (No Content).

Projects API

Get Project Usage

Retrieve project-wide usage statistics (browser minutes and proxy bytes). Replace <your-project-id> with your actual project ID:

curl -s -X GET "https://api.browserbase.com/v1/projects/<your-project-id>/usage" --header "X-BB-API-Key: $BROWSERBASE_TOKEN"

API Endpoints Reference

Session Status Values

Guidelines

1. Session Lifecycle: Sessions auto-terminate after timeout (default 5 minutes). Use keepAlive: true for longer sessions. 2. Contexts: Use contexts to persist login state and avoid repeated authentication. 3. Proxies: Enable proxies for geo-restricted content or to avoid rate limiting. 4. Regions: Choose a region close to your target websites for better performance. 5. Debug URLs: Use debug URLs for real-time human-in-the-loop debugging. 6. Recordings: Session replays use rrweb DOM reconstruction, not video files. 7. Rate Limits: Check your plan limits in the Browserbase dashboard.