> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke a Function

> Invoke Browserbase Functions locally or in production, pass parameters, override browser settings, and retrieve results.

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

## Invoke a local Function

Start the development server:

```bash theme={null}
pnpm bb dev index.ts
```

Send a request to the local Function name:

```bash theme={null}
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:

```bash theme={null}
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](/reference/api/invoke-a-function) for the complete request and response schema.

## Pass parameters

Set `params` to the JSON object that your handler receives:

```json theme={null}
{
  "params": {
    "url": "https://example.com",
    "selector": "h1"
  }
}
```

The serialized `params` object can contain up to 64 KB. Define a Zod [`parametersSchema`](/platform/functions/write#validate-parameters) 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:

```bash theme={null}
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:

```bash theme={null}
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](/reference/api/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](/platform/webhooks/overview) 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](/reference/api/get-a-function-build) returns the build status and built Function IDs.
* [Get Function build logs](/reference/api/get-function-build-logs) returns compiler and bundler output.
* [Get invocation logs](/reference/api/get-invocation-logs) returns your Function's console output.
* [Session Replay](/platform/browser/observability/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.

<Card title="Functions limits" icon="gauge" href="/platform/functions/limits">
  Check the timeout, region, bundle size, and storage constraints.
</Card>