Invoke a Function

You invoke a local Function by name. You invoke a deployed Function by ID.

Invoke a local Function

Start the development server:

pnpm bb dev index.ts

Send a request to the local Function name:

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 Function synchronously and returns the handler’s result in the response.

Invoke a deployed Function

Send a POST request 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 production API returns 202 Accepted with an invocation object. The invocation starts in PENDING or RUNNING. See Invoke a Function for the complete request and response schema.

Pass parameters

Set params to the JSON object that your handler receives:

{
  "params": {
    "url": "https://example.com",
    "selector": "h1"
  }
}

The serialized params object can contain up to 64 KB. Define a Zod parametersSchema to reject invalid input.

Override session settings

sessionConfig in defineFn supplies the browser defaults for every invocation. Set sessionCreateParams in an invoke request to override supported fields for one run:

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"
    },
    "sessionCreateParams": {
      "browserSettings": {
        "context": {
          "id": "CONTEXT_ID",
          "persist": true
        }
      },
      "userMetadata": {
        "jobId": "JOB_ID"
      },
      "timeout": 600
    }
  }'

Browserbase deep-merges sessionCreateParams over the Function version’s sessionConfig. Invocation values win. Defaults that you don’t override remain unchanged. sessionCreateParams doesn’t support region or keepAlive. Set timeout from 60 through 900 seconds. The default is 900 seconds.

Get the result

Poll the invocation by the id returned from the invoke request:

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

An invocation can have these statuses:

Status	Meaning
`PENDING`	Browserbase accepted and queued the invocation.
`RUNNING`	The Function is running.
`COMPLETED`	The handler completed and `results` contains its return value.
`FAILED`	The Function or its browser session failed.

See Get an invocation for the response schema.

Use a webhook instead of polling

Subscribe an endpoint to:

functions.invocations.completed
functions.invocations.failed

Browserbase calls your endpoint when the invocation reaches a terminal state. See Webhooks for delivery and signature verification. Builds emit equivalent functions.builds.running, functions.builds.completed, and functions.builds.failed events.

Inspect builds, logs, and sessions

Use these resources when a publish or invocation fails:

Get a Function build returns the build status and built Function IDs.
Get Function build logs returns compiler and bundler output.
Get invocation logs returns your Function’s console output.
Session Replay shows what happened in the browser.

Every invocation has a sessionId. Use it with Browserbase’s session observability tools to inspect console messages, network activity, and the recording.

Functions limits

Check the timeout, region, bundle size, and storage constraints.

Welcome

Platform

Use cases

Optimization

Account

Invoke a local Function

Invoke a deployed Function

Pass parameters

Override session settings

Get the result

Use a webhook instead of polling

Inspect builds, logs, and sessions

Functions limits

​Invoke a local Function

​Invoke a deployed Function

​Pass parameters

​Override session settings

​Get the result

​Use a webhook instead of polling

​Inspect builds, logs, and sessions

Functions limits

Invoke a local Function

Invoke a deployed Function

Pass parameters

Override session settings

Get the result

Use a webhook instead of polling

Inspect builds, logs, and sessions