Integrating agents - Browserbase Documentation

Once you’ve built an agent in the dashboard, you integrate it into your application over the REST API: trigger runs, pass per-run values, track each run to completion, and read the result. Runs are asynchronous. You create a run, then track it to a terminal state by polling.

To scaffold the integration quickly, open an agent’s run view in the dashboard and use Build API in to open the agent’s API prompt in a coding tool like Cursor.

Endpoints at a glance

Agents define reusable configuration.

Endpoint	Use
Create an agent	Define a reusable agent with a system prompt and result schema.
List agents	Page through your agents.
Get an agent	Fetch a single agent.
Update an agent	Change an agent’s configuration.
Delete an agent	Remove an agent.

Runs are single executions of a task.

Endpoint	Use
Run an agent	Start a run, optionally against an existing agent.
List runs	Page through runs, filtered by agent or status.
Get a run	Fetch a run’s status and result.
List run messages	Stream the run’s step-by-step transcript.

Trigger a run

Start a run with Run an agent. Pass an agentId to run an existing agent, along with per-run options like variables, resultSchema, and browserSettings.

cURL
Node.js
Python

curl -X POST https://api.browserbase.com/v1/agents/runs \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "task": "Find the best matching open role at Browserbase",
    "browserSettings": { "proxies": true }
  }'

const response = await fetch("https://api.browserbase.com/v1/agents/runs", {
  method: "POST",
  headers: {
    "x-bb-api-key": process.env.BROWSERBASE_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    task: "Find the best matching open role at Browserbase",
    browserSettings: { proxies: true },
  }),
});

const { runId } = await response.json();
console.log("Run started:", runId);

import os
import requests

response = requests.post(
    "https://api.browserbase.com/v1/agents/runs",
    headers={
        "x-bb-api-key": os.environ["BROWSERBASE_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "task": "Find the best matching open role at Browserbase",
        "browserSettings": {"proxies": True},
    },
)

print("Run started:", response.json()["runId"])

A call with no agentId creates an ad-hoc run and returns a runId. See Run an agent for every field.

Passing variables

Use variables to pass per-run dynamic values without writing them into the prompt. Each variable pairs a value the placeholder resolves to with an optional description that tells the agent when to use it. Reference a variable in the task or system prompt as %variableName%.

{
  "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "task": "Check in to my flight using confirmation %confirmation%",
  "variables": {
    "confirmation": {
      "value": "XYZ123",
      "description": "The flight confirmation code to enter at check-in"
    }
  }
}

Variables suit values like account numbers, dates of birth, and confirmation codes. The agent fills the placeholder without the value appearing inline in the task.

Tracking a run to completion

A run moves through these states:

PENDING → RUNNING → COMPLETED
                  → FAILED
                  → TIMED_OUT
                  → STOPPED

PENDING and RUNNING are active. The rest are terminal.

Poll for the result

Poll Get a run until the run reaches a terminal state, then read result:

cURL
Node.js
Python

curl https://api.browserbase.com/v1/agents/runs/$RUN_ID \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

async function pollRun(runId: string) {
  const terminal = ["COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"];
  while (true) {
    const response = await fetch(
      `https://api.browserbase.com/v1/agents/runs/${runId}`,
      { headers: { "x-bb-api-key": process.env.BROWSERBASE_API_KEY! } },
    );
    const run = await response.json();
    if (terminal.includes(run.status)) return run;
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

const run = await pollRun(runId);
console.log("Result:", run.result);

import os
import time
import requests

def poll_run(run_id):
    terminal = {"COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"}
    while True:
        response = requests.get(
            f"https://api.browserbase.com/v1/agents/runs/{run_id}",
            headers={"x-bb-api-key": os.environ["BROWSERBASE_API_KEY"]},
        )
        run = response.json()
        if run["status"] in terminal:
            return run
        time.sleep(2)

run = poll_run(run_id)
print("Result:", run.get("result"))

Stream progress

To follow what the agent is doing while it runs, poll List run messages. Save the response’s nextSince and pass it back as since to fetch only newer messages:

curl "https://api.browserbase.com/v1/agents/runs/$RUN_ID/messages?since=$LAST_MESSAGE_ID" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

Messages conform to the AI SDK UIMessage format. Each has a role and a parts array of typed blocks: text, tool calls, reasoning, and files.

Integration is poll-based today: track runs with Get a run and List run messages. Webhook notifications are planned as a future enhancement.

Listing and filtering

Both list endpoints use cursor pagination. Pass the nextCursor from a response back as cursor to fetch the next page. List runs filters by agentId, status, and a startAt/endAt time range:

curl "https://api.browserbase.com/v1/agents/runs?agentId=$AGENT_ID&status=COMPLETED&limit=20" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

List agents pages through your agents with the same cursor pagination pattern.

Next steps

Run an agent

Full request and response reference for a run

List run messages

Stream a run’s step-by-step transcript

Managing files

Retrieve files an agent downloads during a run

How it works

The execution loop, run lifecycle, and observability

​Endpoints at a glance

​Trigger a run

​Passing variables

​Tracking a run to completion

​Poll for the result

​Stream progress

​Listing and filtering

​Next steps

Run an agent

List run messages

Managing files

How it works

Endpoints at a glance

Trigger a run

Passing variables

Tracking a run to completion

Poll for the result

Stream progress

Listing and filtering

Next steps