> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Browserbase

**Authentication:** API key. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow.

## Sample use cases

* Read the pricing page at `acme.com` and pull out each plan's price and limits.
* Search the web for a competitor's latest release notes and summarize what changed.
* Sign in to a vendor portal once, save the session, and reuse that login on every later run.

## Available Tools

#### fetch_page

Fetch a URL and return its content, status code, and headers without starting a browser session. Returns markdown for LLM-friendly reading, or structured JSON against a schema you provide.

#### search_web

Search the web and return structured results with titles and URLs. Pass a result URL to fetch_page to read the page itself.

#### run_agent

Start an autonomous browser agent on a plain-English task, such as finding a pricing page and returning the cheapest plan. Returns a run ID immediately; poll get_agent_run for the result.

#### get_agent_run

Get an agent run by ID: its status, result summary, steps taken, and the failure cause if it did not complete.

#### list_agent_runs

List agent runs, newest first. Filter by status, agent, or a creation-time window.

#### list_run_messages

Get the step-by-step message stream for an agent run: what the agent saw, decided, and did. Use to debug a run that failed or returned an unexpected result.

#### stop_agent_run

Stop a running agent before it finishes, ending its browser session. Use to cut off a run that is looping or heading somewhere unintended.

#### create_agent

Create a reusable agent: a name plus a standing system prompt and result schema that every run started with it inherits. Use when the same browsing job runs repeatedly and should return the same shape each time.

#### get_agent

Get a reusable agent by ID, including its system prompt and result schema.

#### list_agents

List reusable agents. Call this to find an agent to pass to run_agent.

#### update_agent

Update a reusable agent's name, system prompt, or result schema. Only the fields provided change.

#### delete_agent

Delete a reusable agent permanently. Runs already started with it are unaffected.

#### create_session

Start a cloud browser session and return the connection URL an external automation drives. Sessions consume browser minutes until they end, so release them when finished.

#### list_sessions

List browser sessions, filtered by status or by the metadata set when the session was created. Use the running status to find sessions still consuming browser minutes.

#### get_session

Get one browser session by ID: its status, region, timestamps, and proxy bytes used.

#### get_session_logs

Get the browser's command and event log for a session, to debug what an automation or agent run actually did. Available once the session has ended.

#### get_session_live_urls

Get live view and debugger URLs for a running session, so a person can watch or take over the browser. This is how to clear a login or CAPTCHA an automation cannot.

#### release_session

Release a running browser session so it stops consuming browser minutes and frees a concurrency slot.

#### create_context

Create a context that persists cookies and local storage across browser sessions, so a later session resumes an existing login instead of signing in again.

#### get_context

Get a browser context by ID, including which project owns it and when it was created.

#### delete_context

Delete a browser context permanently, discarding the cookies and local storage it held.

#### list_projects

List the Browserbase projects your API key can reach, with each project's concurrency limit and default session timeout.

#### get_project

Get one Browserbase project by ID, including its concurrency limit and default session timeout.

#### get_project_usage

Get the browser minutes and proxy bytes a project has consumed this billing period. Use before starting sessions or agent runs to check remaining allowance.

#### validate_credential

Validate the Browserbase API key with a lightweight call. Returns success plus a short message.