Agent Skills: 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

| 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

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.