Quickstart

This tutorial deploys a Playwright script as a Function, then invokes it through the Browserbase API.

Functions are currently only available in the us-west-2 region.

Prerequisites

You need:

A Browserbase account
A Browserbase API key from Settings
Node.js and pnpm

Create a Functions project

Initialize the project

Run the Functions initializer:

pnpm dlx @browserbasehq/sdk-functions init my-functions-project
cd my-functions-project

The initializer creates package.json, tsconfig.json, .env, and a starter index.ts.

Add your Browserbase API key

Add your API key to .env:

BROWSERBASE_API_KEY=your_api_key

Browserbase resolves the project from the API key. You don’t need a Project ID.

Define the Function

Replace index.ts with a Function that returns the title of a page:

Node.js

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

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

    await page.goto(params.url);

    return { title: await page.title() };
  },
  {
    parametersSchema: z.object({
      url: z.string().url(),
    }),
  },
);

Functions don’t support pnpm workspaces. Keep pnpm-lock.yaml or package-lock.json in the Function project directory, not only at a workspace root.

Test the Function locally

Start the development server

Run:

pnpm bb dev index.ts

The server listens on http://127.0.0.1:14113 and reloads when you change the Function files.

Invoke the local Function

In another terminal, invoke the Function by the name passed to defineFn:

curl --request POST \
  --url http://127.0.0.1:14113/v1/functions/page-title/invoke \
  --header 'Content-Type: application/json' \
  --data '{"params":{"url":"https://example.com"}}'

The local server runs the handler synchronously. The response contains:

{
  "title": "Example Domain"
}

Publish the Function

Publish the entrypoint:

pnpm bb publish index.ts

The command builds each Function reachable from index.ts and prints the Function IDs. Save the ID for page-title. See Deploy Functions for multi-file projects.

Invoke the deployed Function

Production invocations run asynchronously. Start an invocation with the Function ID:

curl --request POST \
  --url https://api.browserbase.com/v1/functions/FUNCTION_ID/invoke \
  --header 'Content-Type: application/json' \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --data '{"params":{"url":"https://example.com"}}'

The API returns 202 Accepted with an invocation object. Copy its id, then poll the invocation:

curl --request GET \
  --url https://api.browserbase.com/v1/functions/invocations/INVOCATION_ID \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

When status is COMPLETED, results contains the value returned by the handler.

Next steps

Write a Function

Configure parameters, browser sessions, and multiple Functions.

Deploy Functions

Publish from the CLI or the Playground.

Invoke a Function

Override session settings and handle asynchronous results.

Welcome

Platform

Use cases

Optimization

Account

Prerequisites

Create a Functions project

Test the Function locally

Publish the Function

Invoke the deployed Function

Next steps

Write a Function

Deploy Functions

Invoke a Function

​Prerequisites

​Create a Functions project

​Test the Function locally

​Publish the Function

​Invoke the deployed Function

​Next steps

Write a Function

Deploy Functions

Invoke a Function

Prerequisites

Create a Functions project

Test the Function locally

Publish the Function

Invoke the deployed Function

Next steps