Skip to main content
Browser Code generates and executes custom JavaScript directly in the browser context for precise control and reliable data extraction.

​
Overview

Step type: execute_javascript Browser Code uses an LLM (Claude) to generate JavaScript based on your prompt, then executes it directly in the browser.

​
How It Works

  • Code Generation: LLM generates JavaScript based on your natural language prompt
  • Execution: Code is evaluated directly in the browser context
  • Variable Support: Supports variable injection using {{variable_name}} syntax
  • Async Support: Can await promises and return values
  • Caching: Caches generated code for repeated execution
  • Timeout: 120 seconds, 3 retry attempts

​
When to Use

Perfect for:
  • Custom data extraction from complex page structures
  • Bulk operations on page elements
  • Direct DOM manipulation
  • Advanced logic too specific for general agents
  • Reliable, repeatable operations
  • Structured data output requirements
Not suitable for:
  • Simple interactions (use Browser Actions instead)
  • Multi-page workflows (use Browser Agents instead)
  • When you need the agent to navigate autonomously
  • When the page structure is highly dynamic and unpredictable

​
Cost

Medium - includes LLM code generation cost plus execution cost.
Generated code is cached, so repeated executions with the same prompt are cheaper!

​
Example Use Cases

​
Data Extraction

Extract structured data from tables: 
{
  "type": "execute_javascript",
  "prompt": "Extract all table rows as JSON with columns: name, email, status",
  "return_by_value": true
}

​
Form Auto-Fill

Fill forms with dynamic data: 
{
  "type": "execute_javascript",
  "prompt": "Auto-fill form fields based on this data object: `{{user_data}}`",
  "variables": {
    "user_data": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  }
}

​
Price Calculation

Calculate totals from page elements: 
{
  "type": "execute_javascript",
  "prompt": "Calculate total price from all items in cart and return sum",
  "return_by_value": true,
  "await_promise": true
}
Find and return specific links: 
{
  "type": "execute_javascript",
  "prompt": "Find all links containing 'download' and return their URLs as an array",
  "return_by_value": true
}

​
Complex Validation

Custom validation logic: 
{
  "type": "execute_javascript",
  "prompt": "Check if all required form fields are filled and return validation status",
  "return_by_value": true
}

​
Configuration Options

​
return_by_value

Get the result value from the code execution: 
{
  "type": "execute_javascript",
  "prompt": "Extract product prices",
  "return_by_value": true
}
Set to false if you only need side effects (like clicking or typing) without a return value.

​
await_promise

Wait for async operations to complete: 
{
  "type": "execute_javascript",
  "prompt": "Fetch data from API and return result",
  "await_promise": true,
  "return_by_value": true
}
Use when your code involves async operations like fetch, setTimeout, or other promises.

​
Structured Output

Browser Code excels at returning structured data:

​
Array Output

{
  "type": "execute_javascript",
  "prompt": "Return array of all product names on the page",
  "return_by_value": true
}
Returns: 
["Product A", "Product B", "Product C"]

​
Object Output

{
  "type": "execute_javascript",
  "prompt": "Extract page metadata as object with title, description, and author",
  "return_by_value": true
}
Returns: 
{
  "title": "Page Title",
  "description": "Page description",
  "author": "Author Name"
}

​
Complex Nested Output

{
  "type": "execute_javascript",
  "prompt": "Extract all products with name, price, and availability status",
  "return_by_value": true
}
Returns: 
[
  {
    "name": "Product A",
    "price": "$29.99",
    "inStock": true
  },
  {
    "name": "Product B",
    "price": "$39.99",
    "inStock": false
  }
]

​
Best Practices

​
Do ✅

  • Be specific about the data structure you want
  • Use return_by_value when you need output
  • Leverage caching for repeated operations
  • Use variables for dynamic content
  • Request structured output (arrays, objects)
  • Specify exact field names for data extraction

​
Don’t ❌

  • Use for multi-page navigation
  • Expect it to handle complex user interactions
  • Use when simple Browser Actions would work
  • Forget to set await_promise for async code
  • Use for tasks requiring visual understanding

​
Writing Effective Prompts

​
❌ Vague Prompt

"Get the data from the page"

​
✅ Specific Prompt

"Extract all table rows from the first table and return as array of objects with fields: name (string), age (number), email (string)"

​
❌ Unclear Output

"Find prices"

​
✅ Clear Output Format

"Find all elements with class 'price' and return their text content as an array of numbers (parse currency to numbers)"

​
Common Patterns

​
Table Extraction

"Extract all rows from table with id 'users-table' as array of objects with columns: id, name, email, role"

​
Form Data Collection

"Get all form input values and return as object with input names as keys"

​
Element Counting

"Count total number of products in the grid and return as number"

​
Conditional Extraction

"Extract all product cards where price is less than $50, return array with name and price"

​
Error Handling

Browser Code includes automatic retry logic:
  • 3 retry attempts for transient failures
  • 120 second timeout per attempt
  • Detailed error messages for debugging
If code generation or execution fails, check:
  1. Is the page structure what you expect?
  2. Are the selectors/elements available?
  3. Is the prompt specific enough?
  4. Do you need await_promise for async code?

​
When to Switch

Consider switching to Browser Actions when:
  • You need simple interactions, not data extraction
  • Natural language instructions are sufficient
  • You want faster development time
  • The task is simple enough for 2 steps
Consider switching to Browser Agents when:
  • You need to navigate multiple pages
  • The workflow requires adaptive decision-making
  • You need autonomous behavior
  • Page structure is unpredictable

​
Comparison: Browser Code vs Browser Assess Page

For data extraction, you can also use browser_assess_page:

​
Browser Code

{
  "type": "execute_javascript",
  "prompt": "Extract products as array with name and price"
}
  • Generates JavaScript code
  • More precise and reliable
  • Better for complex extraction logic

​
Browser Assess Page

{
  "type": "browser_assess_page",
  "assessment": "Extract products from page as list of objects with fields: name (string), price (string)"
}
  • Uses LLM to understand page content
  • Simpler for straightforward extraction
  • Schema validation built-in
Use Browser Code when you need precise selectors and complex logic. Use Browser Assess Page for simpler structured data extraction with schema validation.

Browser Actions

For simple, quick interactions

Browser Agents

For complex multi-step workflows