Browserbase

Cloud browser infrastructure for AI agents and automation. Create browser sessions, persist authentication with contexts, debug live sessions, and retrieve session recordings.

Official docs: https://docs.browserbase.com/

When to Use

Use this skill when you need to:

Create cloud browser sessions for Playwright/Puppeteer automation Persist login state and cookies across sessions using Contexts Debug browser sessions in real-time with live URLs Retrieve session recordings and logs for debugging Manage browser sessions programmatically (list, get, update) Run browser automation with proxy and stealth support Prerequisites Create an account at https://www.browserbase.com/ Get your API Key from the dashboard Settings page Get your Project ID from the dashboard Settings page

Set environment variables:

export BROWSERBASE_API_KEY="your-api-key-here" export BROWSERBASE_PROJECT_ID="your-project-id-here"

Note: Free plans have a concurrent session limit of 1. You'll receive a 429 error if you exceed this limit. Check your plan details in the Browserbase dashboard.

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

How to Use 1. Create a Session

Create a new browser session:

Write /tmp/request.json:

{ "projectId": "" }

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

With timeout and keepAlive:

Write /tmp/request.json:

{ "projectId": "", "timeout": 300, "keepAlive": true }

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

With proxy enabled (requires paid plan):

Write /tmp/request.json:

{ "projectId": "", "proxies": true }

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -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": "", "region": "us-west-2" }

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -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:

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

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

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

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:

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

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:

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

Get Session Details

Get details of a specific session. Replace with the actual session ID:

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

Update Session (Release)

Request to release a session before its timeout to avoid additional charges. Replace with the actual session ID:

Write /tmp/request.json:

{ "status": "REQUEST_RELEASE" }

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

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

Get Debug/Live URLs

Get live debugging URLs for a running session. Replace with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions//debug" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

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 with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions//logs" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

Get Session Recording

Get the rrweb recording of a session. Replace with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions//recording" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

Get Session Downloads

Retrieve files downloaded during a session (returns ZIP file). Replace with the actual session ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/sessions//downloads" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"' --output downloads.zip

Upload Files to Session

Upload files to use in a browser session. Replace with the actual session ID:

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions//uploads" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -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": "" }

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

Save the returned id to use in sessions.

Get Context Details

Retrieve details of a specific context. Replace with the actual context ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/contexts/" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

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 with the actual context ID:

Write /tmp/request.json:

{ "projectId": "", "browserSettings": { "context": { "id": "", "persist": true } } }

bash -c 'curl -s -X POST "https://api.browserbase.com/v1/sessions" --header "Content-Type: application/json" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -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 with the actual context ID:

bash -c 'curl -s -X DELETE "https://api.browserbase.com/v1/contexts/" --header "X-BB-API-Key: $BROWSERBASE_API_KEY" -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 with your actual project ID:

bash -c 'curl -s -X GET "https://api.browserbase.com/v1/projects//usage" --header "X-BB-API-Key: $BROWSERBASE_API_KEY"'

API Endpoints Reference Endpoint Method Description /v1/sessions POST Create a new browser session /v1/sessions GET List all sessions /v1/sessions/{id} GET Get session details (returns array) /v1/sessions/{id} POST Update session (release) /v1/sessions/{id}/debug GET Get live debug URLs /v1/sessions/{id}/logs GET Get session logs /v1/sessions/{id}/recording GET Get session recording (rrweb) /v1/sessions/{id}/downloads GET Get downloaded files (ZIP) /v1/sessions/{id}/uploads POST Upload files to session /v1/contexts POST Create a new context /v1/contexts/{id} GET Get context details /v1/contexts/{id} DELETE Delete a context /v1/projects/{id}/usage GET Get project usage stats Session Status Values Status Description RUNNING Session is currently active COMPLETED Session ended successfully ERROR Session ended with an error TIMED_OUT Session exceeded timeout REQUEST_RELEASE Request to end session Guidelines Session Lifecycle: Sessions auto-terminate after timeout (default 5 minutes). Use keepAlive: true for longer sessions. Contexts: Use contexts to persist login state and avoid repeated authentication. Proxies: Enable proxies for geo-restricted content or to avoid rate limiting. Regions: Choose a region close to your target websites for better performance. Debug URLs: Use debug URLs for real-time human-in-the-loop debugging. Recordings: Session replays use rrweb DOM reconstruction, not video files. Rate Limits: Check your plan limits in the Browserbase dashboard.

安装