n8n quickstart - Browserbase Documentation

Get your Browserbase credentials

Copy your API Key. If you still rely on a Project ID for older workflows, keep that available as well.Don’t have an account yet? Sign up at browserbase.com.

Choose model credentials

For browser agents, you can use Browserbase Model Gateway with only your Browserbase API key. Model Gateway lets you switch between supported models in the node. Browserbase bills model usage at market rate through your Browserbase account.You can also bring your own API key from the model provider whose models you’ll use. Choose one:

Google: Google AI Studio
OpenAI: OpenAI Platform
Anthropic: Anthropic Console

If you bring your own Model API Key, it must match the provider of both your Driver Model and Agent Model. For example, if you select google/gemini-2.5-flash as your driver and google/gemini-2.5-computer-use-preview-10-2025 as your agent model, you need a Google API key.

Install the community node

In your n8n instance:

Go to Settings > Community Nodes
Click Install a community node
Enter n8n-nodes-browserbase
Click Install

Requires n8n v1.60.0 or later. If you’re self-hosting, make sure your instance is up to date.

Configure credentials

Go to Credentials > Add Credential
Search for “Browserbase” and select Browserbase API
Fill in the three fields:

Field	Value
Browserbase API Key	Your API key from Step 1
Browserbase Project ID	Optional legacy project ID from Step 1
Model API Key	Optional. Only required when using the `Agent` resource with your own model provider key instead of Model Gateway

Click Save

All Browserbase nodes in your workflows use these credentials. You only need to set them up once.

Add the Browserbase node

Create a new workflow (or open an existing one)
Click + to add a node and search for “Browserbase”
Select the Resource you want to use:

Resource	Use case
Agent	Run a Stagehand-powered browser agent in a Browserbase session
Search	Find relevant URLs with the Search API without creating a browser session
Fetch	Retrieve page content with the Fetch API without creating a browser session

Configure the Agent resource

To run a browser agent, choose Resource = Agent and configure the required fields:

Field	Description
Resource	`Agent`
Starting URL	The page where the agent begins (e.g., `https://news.ycombinator.com`)
Instruction	Natural language task (e.g., “Find the top 3 stories and return their titles and URLs”)
Driver Model	Powers navigation and DOM interactions. Default: `google/gemini-2.5-flash`
Mode	`CUA` (vision), `DOM` (selectors), or `Hybrid` (both)
Agent Model	Orchestration model. Available options change based on selected mode

When using your own Model API Key, the Driver Model and Agent Model must be from the same provider. With Model Gateway, you only need your Browserbase API key.

Try Search or Fetch

The same node also supports lightweight Browserbase APIs:Search

Field	Description
Resource	`Search`
Query	Search query to execute
Number of Results	Optional. How many results to return

Fetch

Field	Description
Resource	`Fetch`
URL	URL to fetch
Follow Redirects	Optional. Follow HTTP redirects
Allow Insecure SSL	Optional. Allow invalid SSL certificates
Use Proxies	Optional. Route traffic through Browserbase proxies

Search and Fetch only require your Browserbase API key. They do not create a browser session.

Run your workflow

Click Test Workflow to execute. When Resource = Agent, the node returns an AgentResult object:

{
  "success": true,
  "message": "Task completed successfully",
  "actions": [
    { "type": "act", "action": "clicked submit button" }
  ],
  "completed": true,
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 340,
    "inference_time_ms": 2500
  },
  "sessionId": "abc-123"
}

When Resource = Search or Fetch, the node returns the corresponding Search or Fetch API response, which you can pass to downstream n8n nodes.You can connect additional nodes to process any of these outputs. Send them to a database, spreadsheet, Slack channel, or any other n8n integration.

Optional settings

Browser options

Option	Type	Default	Description
Verified	boolean	`false`	Enable Verified browser sessions
Block Ads	boolean	`true`	Block ads during browsing
Record Session	boolean	`true`	Record the browser session for replay in the Browserbase Dashboard
Solve Captchas	boolean	`false`	Automatically solve captchas encountered during execution
Viewport Width	number	`1288`	Browser viewport width in pixels
Viewport Height	number	`711`	Browser viewport height in pixels

Session options

Option	Type	Default	Description
Region	select	`us-west-2`	Region where the browser runs. Options: `us-west-2` (Oregon), `us-east-1` (Virginia), `eu-central-1` (Frankfurt), and `ap-southeast-1` (Singapore)
Timeout	number	`300`	Session timeout in seconds
Use Proxies	boolean	`true`	Route traffic through residential proxies

Agent options

Option	Type	Default	Description
Max Steps	number	`20`	Maximum number of steps the agent can take
System Prompt	string		Custom system prompt to guide the agent’s behavior
Highlight Cursor	boolean	`true`	Highlight cursor during execution (CUA/Hybrid modes only)
Variables	collection		Pass sensitive data to the agent using `%name%` placeholders in your instruction. The LLM sees placeholder names and optional descriptions but never the actual values. Learn more. (DOM and Hybrid modes)

Example workflows

Agent: data extraction

Starting URL: https://news.ycombinator.com
Instruction: Find the top 3 stories and return their titles and URLs

Agent: form filling (with variables)

Starting URL: https://example.com/contact
Instruction: Fill out the contact form with name %name% and email %email%, then submit
Variables: name = John Doe, email = john@example.com

Agent: navigation + action

Starting URL: https://github.com
Instruction: Search for "stagehand" and click on the first repository result

Search: web discovery

Query: browserbase documentation
Number of Results: 5

Fetch: lightweight retrieval

URL: https://www.browserbase.com
Follow Redirects: true

The Browserbase node has usableAsTool enabled for browser agents. You can use it as a tool from n8n’s built-in AI Agent node so higher-level agents can decide when to send work to a browser agent.

View on GitHub

Browse the source code, report issues, or contribute to the n8n community node.

​Optional settings

​Browser options

​Session options

​Agent options

​Example workflows

View on GitHub

Optional settings

Browser options

Session options

Agent options

Example workflows