Use Browser Node

Run an AI-powered browser automation agent that can navigate websites, interact with elements, and extract data.

The Use Browser node uses a headless browser controlled by an AI model to perform multi-step web interactions. Unlike the Browse Web node (which only fetches page content), the Use Browser node can click buttons, fill forms, scroll, navigate between pages, and perform complex multi-step browser tasks autonomously.

Parameters

Parameter	Type	Required	Default	Description
instructions	string	✅		Natural language instructions for the browser agent
connectorId	string	✅		Browser connector ID (configured externally)
proxyMode	string	❌	no_proxy	Proxy mode for browser traffic
proxyCountry	string	❌	null	Country code for the country proxy when proxy is used
includeScreenshotsInOutput	boolean	❌	false	Show screenshots in the results after the run ends

instructions

Type: string | Required: ✅

Natural language instructions describing what the browser agent should do. The agent interprets these instructions and performs the necessary browser actions (navigation, clicking, typing, scrolling, etc.) to accomplish the task.

The instructions field supports ${...} template syntax for inserting dynamic values from previous nodes. For example, Go to ${input.url} and extract the main content.

Examples:

• Go to LinkedIn and search for "AI engineers in Berlin". Extract the first 10 profile names and headlines.
• Navigate to the company website, find the pricing page, and extract all plan names and prices.
• Log into the dashboard, navigate to the reports section, and download the latest monthly report.

connectorId

Type: string | Required: ✅

The ID of a browser connector (use_browser type) that provides the browser session. This connector must be configured and authenticated before using the node.

proxyMode

Type: string | Required: ❌ | Default: no_proxy

Controls whether the browser runs without a proxy or through a country proxy.

Supported values:

• no_proxy - run the browser directly
• country_proxy - route browser traffic through a country proxy

proxyCountry

Type: string | Required: ❌ | Default: null

Two-letter lowercase country code used when proxyMode is country_proxy (for example us, de, or gb). This field must be set when using the country proxy and is ignored when proxyMode is no_proxy.

includeScreenshotsInOutput

Type: boolean | Required: ❌ | Default: false

Controls whether screenshots appear in the results after the run ends.

• false - screenshots are available only while the node is actively running in Watch
• true - completed runs keep screenshots in monitor.steps

Configuring This Node

When you add a Use Browser node to your workflow and open its configuration panel, you will walk through the following steps:

1. Browser Session Setup

The first thing you see is a connector selector for the use_browser connector type. Authentication is required.

• If no browser connector exists yet: An empty state is displayed with the title "Browser Setup" and the description: "Launch a live browser session to log into your accounts (LinkedIn, etc.). Your login will be saved for future workflow runs." Click the "Set up Browser Connector" button to create a new browser connector and open a live browser window where you can log into the sites the agent will need to access.

• If a browser connector already exists: A card is shown with the text "Open a live browser session to add or update your saved logins. Changes will be used in future workflow runs." Click the "Edit Browser Connector" button to open a live browser dialog where you can add new logins or update existing ones. Any changes are saved and used automatically in future workflow runs.

2. Run Mode and Error Handling

• Run Mode — A dropdown that controls how the node processes input data:
  • Item — Runs once per array element. Use item in template expressions.
  • Input — Runs once for the entire input. Use input in template expressions.
• Continue on Error — A toggle that, when enabled, allows the workflow to continue executing downstream nodes even if this node encounters an error. When disabled (the default), an error in the browser agent stops the workflow.

3. AI Instructions

A template text area where you write natural language instructions for the browser agent. This field supports ${...} template syntax for inserting dynamic values from previous node outputs — for example, Navigate to ${input.url} and extract all product prices.

4. Location Selection

A dropdown labeled Location lets you choose how the browser should connect:

• Default location - use a direct connection
• Country-specific proxy - pick a country to use a proxy for that location

When a country is selected, the node stores proxyMode: "country_proxy" and proxyCountry with the selected country code.

Watch

While the Use Browser node is actively running, a Watch panel appears in the configuration view. It displays a card with the text "Watch the live agent browser while this node is running." and a "Watch" button.

• The button is only enabled while the node is actively executing.
• Clicking it opens a live view of the browser the agent is controlling, so you can watch its actions in real time.
• This is useful for debugging, verifying that the agent is navigating correctly, or monitoring long-running tasks.

Screenshot Retention

The node also includes an Include screenshots in results toggle:

• Off (default) - screenshots are shown only during the live run in Watch
• On - screenshots also appear in the results after the run ends

Examples

1. Scrape LinkedIn Search Results

Navigate to LinkedIn and extract profile data:

Parameters:

{
  "instructions": "Go to LinkedIn search results for 'AI engineers in Berlin'. Extract the first 10 profile names, headlines, and profile URLs.",
  "connectorId": "<your-browser-connector-id>"
}

2. Extract Pricing Information

Visit a competitor's pricing page and extract plan details:

Parameters:

{
  "instructions": "Navigate to https://example.com/pricing. Extract all pricing plan names, prices, and feature lists.",
  "connectorId": "<your-browser-connector-id>"
}

3. Fill and Submit a Form

Automate form submission on a website:

Parameters:

{
  "instructions": "Go to https://example.com/contact. Fill in the name field with 'John Doe', email with 'john@example.com', and message with 'I would like to schedule a demo.' Then click the Submit button.",
  "connectorId": "<your-browser-connector-id>"
}

4. Use a US Location

Run the browser through a US proxy:

Parameters:

{
  "instructions": "Go to https://example.com and verify what pricing is shown for US visitors.",
  "connectorId": "<your-browser-connector-id>",
  "proxyMode": "country_proxy",
  "proxyCountry": "us"
}

Output Structure

The node returns the result of the browser automation session:

{
  "is_done": true,
  "is_successful": true,
  "result": "Successfully extracted 10 profiles from LinkedIn search results...",
  "urls": ["https://www.linkedin.com/search/results/people/..."],
  "errors": [],
  "steps": 12,
  "duration_seconds": 48.2,
  "model_used": "bu-latest"
}

Field	Type	Description
result	string	The extracted data or result description
is_done	boolean	Whether the agent completed its task
is_successful	boolean	Whether the task was completed successfully
urls	array	URLs visited or returned by the browser run
errors	array	Any non-empty errors encountered during execution
steps	number	Number of browser-agent steps taken
duration_seconds	number	Total runtime of the browser session in seconds
model_used	string	The internal browser-use model used for the run, if reported

If screenshot retention is enabled, the persisted node output also keeps a monitor object with step history that can include screenshots. If retention is disabled, the monitor object remains but completed steps no longer include screenshot payloads.

Important Notes

• Browser connector required: You must create a use_browser connector before using this node. You can set one up directly from the node's configuration panel or from the Connectors page.
• Authentication required: The browser connector requires authentication. During setup, a live browser window opens so you can log into the websites the agent will interact with. Your login sessions are saved and reused across workflow runs.
• Model selection is not user-configurable: The workflow node does not accept a user-provided model parameter. Needle currently chooses the browser-use model internally and sends bu-latest to the backend service.
• Location settings are optional: If you pick a country in the Location dropdown, the node sends proxyMode: "country_proxy" together with proxyCountry. Otherwise it runs with proxyMode: "no_proxy".
• Screenshot retention is optional: By default, screenshots are available only while the node is running in Watch. Turn on Include screenshots in results if you want them to appear in the results after the run ends.
• Task completion: The agent autonomously determines when it has completed the task. If it cannot complete the task, it returns is_successful: false.
• Continue on Error: Enable the Continue on Error toggle if you want downstream nodes to execute even when the browser agent fails. This is useful in workflows where partial results are acceptable.
• Credit consumption: Browser automation consumes more credits than simple web browsing because the AI model is invoked multiple times to navigate and interact with the page.
• Use case distinction: Use the Browse Web node for simple page content retrieval. Use the Use Browser node for multi-step interactions that require clicking, scrolling, or form filling.