Functions Reference

Browser Functions is currently in open beta! While we don’t intend to make any major changes to the public API, things may still change without notice. If you have any questions or feedback, please reach out to our customer engineering team!

Defining Functions

Basic Function

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";

defineFn("function-name", async (ctx, params) => {
  const browser = await chromium.connectOverCDP(ctx.session.connectUrl);
  const context = browser.contexts()[0];
  const page = context?.pages()[0];

  // Your automation code here

  return { result: "your data" };
});

Function Parameters

Function Name - Unique identifier for your function (used in the “invoke function” HTTP request)
Handler - Async function that receives:
- ctx - Context object with session information
- params - Parameters passed when invoking the function
Options - Optional configuration object for session settings

Make sure that you give each function in your codebase a unique name! Function names are unique per project. The name parameter serves as a function’s “Logical ID” (a unique, human-friendly identifier), meaning reusing a name string could lead to overwriting an existing built function with the same name.

Context Object

The ctx parameter provides access to the browser session:

{
  session: {
    connectUrl: string;  // CDP connection URL
    id: string;          // Session ID
  }
}

Function Response

Return any JSON-serializable data from your function:

return {
  success: true,
  data: { ... },
  message: "Operation complete"
};

Session Configuration

Configure browser session settings using the third parameter:

defineFn(
  "stealth-function",
  async (ctx, params) => {
    // Your function code
  },
  {
    sessionConfig: {
      browserSettings: {
        advancedStealth: true,
        solveCaptchas: true,
      },
      proxies: true,
      viewport: {
        width: 1920,
        height: 1080,
      },
    },
  }
);

Available Options

All session creation options are supported:

browserSettings - Configure stealth mode, CAPTCHA solving, and browser behavior
proxies - Enable proxy settings for IP rotation
viewport - Set custom screen dimensions
context - Use browser contexts for session persistence
extensions - Load custom extensions

Complete Example

Here’s a full example that fills out a contact form:

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";

defineFn(
  "fill-contact-form",
  async (ctx, params) => {
    const browser = await chromium.connectOverCDP(ctx.session.connectUrl);
    const context = browser.contexts()[0];
    const page = context?.pages()[0];

    if (!page) {
      console.error("Failed to create a page");
      return { error: "No page available" };
    }

    try {
      // Navigate to the contact page
      await page.goto("https://www.browserbase.com/contact");

      // Fill out the form
      await page.locator("#firstName").fill("Browser");
      await page.locator("#lastName").fill("Functions");
      await page.locator("#email-label").fill("[email protected]");
      await page.locator("#jobTitle-label").fill("Professional robot");
      await page.locator("#companyName-label").fill("Browserbase");

      // Select an option from dropdown
      await page.locator("button#helpOption").click();
      await page.locator("#helpOption-demo").click();

      return {
        success: true,
        message: "Form filled successfully"
      };
    } catch (error: unknown) {
      console.error("Error filling form:", error);
      return {
        error: "Failed to fill form",
        details: String(error)
      };
    }
  },
  {
    sessionConfig: {
      browserSettings: {
        advancedStealth: true,
      },
    },
  }
);

Publishing Functions

Multiple Functions (single file)

Define multiple functions in a single file:

index.ts

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";

// Function 1: Screenshot
defineFn("take-screenshot", async (ctx, params) => {
  const browser = await chromium.connectOverCDP(ctx.session.connectUrl);
  const page = browser.contexts()[0]?.pages()[0];

  await page.goto(params.url);
  const screenshot = await page.screenshot({ encoding: "base64" });

  return { screenshot };
});

// Function 2: Extract Text
defineFn("extract-text", async (ctx, params) => {
  const browser = await chromium.connectOverCDP(ctx.session.connectUrl);
  const page = browser.contexts()[0]?.pages()[0];

  await page.goto(params.url);
  const text = await page.textContent(params.selector);

  return { text };
});

Both functions will be deployed when you run pnpm bb publish index.ts.

Multiple Functions (multiple files)

Define multiple functions in multiple files:

index.ts

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";

import "screenshot-fn.ts"
// Import any other files that contain `defineFn` calls in the same way

// Function 1: Screenshot
defineFn("take-screenshot", async (ctx, params) => {
  const browser = await chromium.connectOverCDP(ctx.session.connectUrl);
  const page = browser.contexts()[0]?.pages()[0];

  await page.goto(params.url);
  const screenshot = await page.screenshot({ encoding: "base64" });

  return { screenshot };
});

screenshot-fn.ts

import { defineFn } from "@browserbasehq/sdk-functions";
import { chromium } from "playwright-core";

// Function 2: Extract Text
defineFn("extract-text", async (ctx, params) => {
  const browser = await chromium.connectOverCDP(ctx.session.connectUrl);
  const page = browser.contexts()[0]?.pages()[0];

  await page.goto(params.url);
  const text = await page.textContent(params.selector);

  return { text };
});

Both functions will be deployed when you run pnpm bb publish index.ts.

Invoke a Function

Get Build Result

Retrieve information about the function(s) built or updated by a build:

curl https://api.browserbase.com/v1/functions/builds/BUILD_ID \
  -H "x-bb-api-key: $BB_API_KEY"

This returns function ID(s) needed for invocation.

Pass Parameters to Functions

Access parameters in your function handler:

defineFn("parameterized-function", async (ctx, params) => {
  const { url, searchTerm } = params;

  // Use parameters in your automation
  await page.goto(url);
  await page.fill("#search", searchTerm);

  return { searched: searchTerm };
});

Invoke with parameters:

curl -X POST https://api.browserbase.com/v1/functions/FUNCTION_ID/invoke \
  -H "Content-Type: application/json" \
  -H "x-bb-api-key: $BB_API_KEY" \
  -d '{
    "url": "https://example.com",
    "searchTerm": "browser automation"
  }'

Best Practices

Error Handling

Unhandled errors will be caught by our runners and reported as an error. If you want to gracefully handle your errors (for example, return information on the failure), wrap your automation code in try-catch blocks:

defineFn("safe-function", async (ctx, params) => {
  try {
    const browser = await chromium.connectOverCDP(ctx.session.connectUrl);
    const page = browser.contexts()[0]?.pages()[0];

    // Your automation code

    return { success: true };
  } catch (error) {
    console.error("Function error:", error);
    return {
      success: false,
      error: String(error)
    };
  }
});

Timeouts

Set appropriate timeouts for navigation and actions when using Playwright:

await page.goto(url, { timeout: 30000 });
await page.waitForSelector("#element", { timeout: 10000 });

Logging

Use console methods for debugging - logs are captured and available in invocation logs:

console.log("Starting navigation to:", url);
console.warn("Potential issue detected:", warning);
console.error("Critical error:", error);

Session Cleanup

Browser sessions automatically close when your function completes. No manual cleanup is required.

Monitoring and Debugging

Every function invocation creates a browser session that you can inspect as with any other Browserbase session:

Session Replays - View the function execution in the Session Inspector
Console Logs - See all logged messages during execution
Network Activity - Inspect HTTP requests and responses
Performance Metrics - Monitor execution time and resource usage

Session Replay

Learn how to debug functions using session replays

Next Steps

Session Configuration

Learn about all available session configuration options

Stealth Mode

Configure anti-bot detection for your functions

Browser Contexts

Persist authentication and session state

API Reference

Complete Browserbase API documentation

Introduction

Fundamentals

Features

Use Cases

Guides

Integrations

Defining Functions

Basic Function

Function Parameters

Context Object

Function Response

Session Configuration

Available Options

Complete Example

Publishing Functions

Multiple Functions (single file)

Multiple Functions (multiple files)

Invoke a Function

Get Build Result

Pass Parameters to Functions

Best Practices

Error Handling

Timeouts

Logging

Session Cleanup

Monitoring and Debugging

Session Replay

Next Steps

Session Configuration

Stealth Mode

Browser Contexts

API Reference

Introduction

Fundamentals

Features

Use Cases

Guides

Integrations

​Defining Functions

​Basic Function

​Function Parameters

​Context Object

​Function Response

​Session Configuration

​Available Options

​Complete Example

​Publishing Functions

​Multiple Functions (single file)

​Multiple Functions (multiple files)

​Invoke a Function

​Get Build Result

​Pass Parameters to Functions

​Best Practices

​Error Handling

​Timeouts

​Logging

​Session Cleanup

​Monitoring and Debugging

Session Replay

​Next Steps

Session Configuration

Stealth Mode

Browser Contexts

API Reference

Defining Functions

Basic Function

Function Parameters

Context Object

Function Response

Session Configuration

Available Options

Complete Example

Publishing Functions

Multiple Functions (single file)

Multiple Functions (multiple files)

Invoke a Function

Get Build Result

Pass Parameters to Functions

Best Practices

Error Handling

Timeouts

Logging

Session Cleanup

Monitoring and Debugging

Next Steps