browserbase

What this skill does

## 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`:
```json
{
  "projectId": "<your-project-id>"
}
```

```bash
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`:
```json
{
  "projectId": "<your-project-id>",
  "timeout": 300,
  "keepAlive": true
}
```

```bash
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`:
```json
{
  "projectId": "<your-project-id>",
  "proxies": true
}
```

```bash
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`:
```json
{
  "projectId": "<your-project-id>",
  "region": "us-west-2"
}
```

```bash
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:

```bash
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):**

```bash
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:
```bash
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:
```bash
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:

```bash
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`:
```json
{
  "status": "REQUEST_RELEASE"
}
```

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:
```json
{
  "projectId": "<your-project-id>"
}
```

```bash
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:

```bash
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`:
```json
{
  "projectId": "<your-project-id>",
  "browserSettings": {
    "context": {
      "id": "<your-context-id>",
      "persist": true
    }
  }
}
```

```bash
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:

```bash
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:

```bash
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 ar