---
name: browserbase
description: Use when building autonomous browser agents, automating web interactions, extracting data from websites, running end-to-end tests, or deploying browser-based workflows. Reach for Browserbase when you need cloud browsers, web search, page fetching, agent automation, or serverless browser functions.
metadata:
    mintlify-proj: browserbase
    version: "1.0"
---

# Browserbase Skill

## Product summary

Browserbase is a cloud browser platform that provides APIs for browser automation, web data extraction, and autonomous agents. It offers cloud-hosted headless browsers, web search, page fetching, serverless Functions, and AI-powered Agents that can browse and interact with websites autonomously. Agents describe tasks in natural language; browser sessions give you deterministic control via Playwright, Puppeteer, or Stagehand. Key files: `.env` for `BROWSERBASE_API_KEY`. Primary SDKs: Node.js (`@browserbasehq/sdk`) and Python (`browserbase`). REST API at `https://api.browserbase.com/v1/`. See [Browserbase docs](https://docs.browserbase.com) for full reference.

## When to use

**Use Browserbase Agents when:**
- You want an autonomous agent to complete a web task from a natural language instruction
- You don't want to maintain Playwright, Stagehand, model, or runtime orchestration
- You need to scale across many sites without writing one script per target
- The task involves browsing, clicking, typing, searching, extracting data, or file handling

**Use Browser Sessions when:**
- You need deterministic, code-driven browser control in your own code
- You're building custom automation logic with Playwright, Puppeteer, or Stagehand
- You need fine-grained control over page interactions and state management
- You want to reuse browser contexts or maintain session state across multiple operations

**Use Functions when:**
- You have existing Playwright/Stagehand code you want to deploy as an API
- You need serverless browser execution triggered by webhooks or scheduled jobs
- You want Browserbase to manage browser lifecycle for each invocation
- You need low-latency access to a browser from your code

**Use Fetch API when:**
- The page doesn't require JavaScript execution or interaction
- You just need content extraction and performance/cost matter
- The response is under 5 MB and loads within 60 seconds
- You want the cheapest option for read-only page retrieval

**Use Search API when:**
- Your agent doesn't yet know where information lives on the web
- You need to discover URLs before opening a browser
- You want quick context before escalating to a full browser session

## Quick reference

### Core APIs and SDKs

| Tool | Use case | Cost | Latency |
|------|----------|------|---------|
| **Agents** | Natural language task automation | High (includes browser + model) | Slow (async, reasoning overhead) |
| **Browser Sessions** | Deterministic automation with code | Medium (per-session) | Fast (direct control) |
| **Functions** | Deploy custom browser code as API | Medium (per-invocation) | Fast (co-located with browser) |
| **Fetch** | Read-only page content | Low | Fast (no browser) |
| **Search** | Discover URLs from queries | Low | Fast (no browser) |

### Essential SDK methods (Node.js)

```javascript
// Create a session
const session = await bb.sessions.create({ browserSettings: {...} });

// Create and run an Agent
const { agentId, runId } = await bb.agents.runs.create({ task: "..." });

// Poll for Agent completion
const run = await bb.agents.runs.retrieve(runId);

// Get Agent messages (step-by-step transcript)
const messages = await bb.agents.runs.listMessages(runId);

// Fetch a page
const response = await bb.fetchAPI.create({ url: "..." });

// Search the web
const results = await bb.search.create({ query: "..." });
```

### Session configuration options

| Option | Purpose | Example |
|--------|---------|---------|
| `region` | Browser location (latency) | `"us-west-2"`, `"eu-central-1"`, `"ap-southeast-1"` |
| `timeout` | Session duration (seconds) | `3600` (1 hour), max `21600` (6 hours) |
| `keepAlive` | Survive disconnections | `true` for long-running sessions |
| `proxies` | Route through proxy network | `true` or `{ geolocation: { country: "US" } }` |
| `browserSettings.verified` | Real fingerprints (Scale plan) | `true` for protected sites |
| `browserSettings.solveCaptchas` | Auto-solve CAPTCHAs | `true` (default) |
| `browserSettings.recordSession` | Enable replay | `true` (default) |
| `browserSettings.viewport` | Screen size | `{ width: 1920, height: 1080 }` |

### Agent run lifecycle

```
PENDING → RUNNING → COMPLETED
                  → FAILED
                  → TIMED_OUT
                  → STOPPED
                  → PAUSED (can resume)
```

Poll `get-a-run` until terminal state. Read `result` (structured output) and `sessionId` (for replay).

## Decision guidance

### When to use Agents vs. Browser Sessions vs. Functions

| Scenario | Use | Reason |
|----------|-----|--------|
| "Automate a task described in English" | **Agents** | No code needed; Browserbase owns the loop |
| "I have Playwright code I want to run" | **Browser Sessions** | Direct control; you own the loop |
| "Deploy my Playwright code as an API" | **Functions** | Serverless execution; Browserbase manages lifecycle |
| "I need to click, type, and extract from a form" | **Browser Sessions** or **Agents** | Agents if you want natural language; Sessions if you need determinism |
| "Just get me the HTML/markdown from a URL" | **Fetch** | Cheapest; no browser needed |
| "Find relevant URLs for a query" | **Search** | Cheap discovery; escalate to browser if needed |

### When to use Verified vs. standard browser

| Condition | Use |
|-----------|-----|
| Site has bot protection (Cloudflare, DataDome, etc.) | **Verified** (Scale plan) |
| Site blocks automation or requires high trust signals | **Verified** + **Proxies** |
| Simple public sites, no anti-bot measures | Standard browser |
| Proof of concept or testing | Standard browser + proxies |

### When to enable Proxies

| Condition | Use |
|-----------|-----|
| Site blocks your IP or returns 403 | **Enable proxies** |
| Need geolocation-specific content | **Proxies with geolocation** |
| Site doesn't block automation | Leave disabled (faster, cheaper) |

## Workflow

### Running an Agent (typical task)

1. **Understand the task.** What does the user want the agent to do? Is it a one-off run or a reusable agent?
2. **Create or retrieve an Agent.** Use the dashboard for quick prototyping, or call `create-an-agent` API for programmatic setup. Set `systemPrompt` and `resultSchema`.
3. **Create a run.** Call `agents.runs.create()` with the task description and optional `browserSettings` (proxies, verified, context).
4. **Poll for completion.** Call `get-a-run` every 2–5 seconds until status is terminal (`COMPLETED`, `FAILED`, `TIMED_OUT`, `STOPPED`).
5. **Inspect the result.** Read `result` (structured output) and `sessionId`. Use sessionId to view replay in the dashboard.
6. **Handle pauses.** If status is `PAUSED`, the agent is waiting for input. Call `resume-a-run` with the user's response.
7. **Debug if needed.** Call `list-run-messages` to see step-by-step transcript. Open session replay at `https://browserbase.com/sessions/{sessionId}`.

### Creating and using a Browser Session

1. **Create a session.** Call `sessions.create()` with desired `browserSettings` (region, viewport, proxies, verified, etc.).
2. **Get the connection URL.** Extract `session.connectUrl` from the response.
3. **Connect with your framework.** Use Playwright (`chromium.connectOverCDP()`), Puppeteer (`puppeteer.connect()`), or Stagehand (`browserbase.connect()`).
4. **Automate.** Write your browser logic (navigate, click, extract, etc.).
5. **Disconnect.** Close the browser; Browserbase automatically terminates the session.
6. **Review the session.** Open `https://browserbase.com/sessions/{sessionId}` to watch the replay.

### Deploying a Function

1. **Write your handler.** Use `defineFn()` with Stagehand, Playwright, or Puppeteer. Access the browser via `context.session.connectUrl`.
2. **Test locally.** Run `browse dev` to test the function with a local dev server.
3. **Deploy.** Run `browse deploy` to publish the function and create a version.
4. **Invoke.** Call the function via the API (`invoke-a-function`) with parameters.
5. **Monitor.** Poll `get-an-invocation` for status, or subscribe to webhooks for `functions.invocations.*` events.

### Fetching a page

1. **Call Fetch API.** Use `fetchAPI.create({ url: "..." })` with optional `format` ("raw", "markdown", "json") and `schema`.
2. **Check the response.** Inspect `statusCode`, `content`, and `contentType`.
3. **Handle errors.** If 502 (content too large) or 504 (timeout), fall back to a browser session.
4. **Use the content.** Pass markdown or JSON to downstream agents or pipelines.

## Common gotchas

- **Agent runs are asynchronous.** Don't expect instant results. Poll the API or use webhooks. Typical runs take 10–60 seconds.
- **Agents don't guarantee determinism.** The same task may produce different results on different runs due to model reasoning. Use `resultSchema` to enforce structure.
- **Session timeouts are strict.** Default timeout is project-wide; override per-session. Sessions terminate at timeout; no grace period.
- **Fetch doesn't execute JavaScript.** If a page loads content via XHR or JS, Fetch returns an empty shell. Use a browser session instead.
- **Fetch has a 5 MB limit.** Large responses return 502. Detect this and fall back to a browser session.
- **Proxies add latency.** Enable only if the site blocks your IP. Disable for speed.
- **Verified is Scale plan only.** Standard browsers work for most sites. Use Verified only for heavily protected sites.
- **CAPTCHA solving takes time.** Budget up to 30 seconds per CAPTCHA. Pair with proxies for better success rates.
- **Recording is enabled by default.** Disable `recordSession: false` if you don't need replay (saves cost).
- **Contexts require explicit persistence.** Create a context, use it in a session, and set `persist: true` to reuse it. Otherwise, it's discarded.
- **Functions have a 25 MB bundle limit.** Minify dependencies. Lockfile is required in the project directory.
- **Rate limits apply per plan.** Developer plan: 25 concurrent sessions. Hitting the limit returns HTTP 429. Check `x-ratelimit-remaining` header.
- **Agent Identity (Verified, Web Bot Auth) requires explicit opt-in.** Standard sessions don't use them; enable in `browserSettings`.
- **Search and Fetch don't create browser sessions.** They're cheap read-only APIs. Escalate to a browser only when needed.

## Verification checklist

Before submitting work with Browserbase:

- [ ] **API key is set.** Verify `BROWSERBASE_API_KEY` is in `.env` or environment.
- [ ] **Correct tool chosen.** Did you pick Agents, Sessions, Functions, Fetch, or Search for the task?
- [ ] **Session/run configuration is correct.** Region, timeout, proxies, verified, and browserSettings match the requirement.
- [ ] **Polling logic is in place.** For async operations (Agents, Functions), poll until terminal state or use webhooks.
- [ ] **Error handling covers rate limits.** Check for HTTP 429 and retry with backoff.
- [ ] **Replay is accessible.** For debugging, confirm you can open the session at `https://browserbase.com/sessions/{sessionId}`.
- [ ] **Result schema is valid JSON Schema.** If using Agents, validate the schema structure.
- [ ] **Fetch fallback is implemented.** If using Fetch, catch 502 and 504 errors and fall back to a browser session.
- [ ] **Cost is reasonable.** Agents are expensive; consider Fetch or Search first. Functions are cheaper for scheduled/webhook tasks.
- [ ] **No hardcoded credentials.** Use Secrets for Functions or environment variables for sessions.

## Resources

- **[Browserbase llms.txt](https://docs.browserbase.com/llms.txt)** — Comprehensive page-by-page navigation for all documentation.
- **[Agents Overview](https://docs.browserbase.com/platform/agents/overview)** — When to use Agents, run lifecycle, and built-in tools.
- **[Browser Sessions Getting Started](https://docs.browserbase.com/platform/browser/getting-started/create-browser-session)** — How to create and configure sessions.
- **[Functions Overview](https://docs.browserbase.com/platform/functions/overview)** — Deploy custom browser code as serverless functions.

---

> For additional documentation and navigation, see: https://docs.browserbase.com/llms.txt