# Browserbase

> Give a workflow a real browser in the cloud. Read a page that a plain request comes back empty on, pull named details straight out of it, search the web, or describe a job in plain language and have a browser sign in, click through and bring back what it found.

App · AI Agents · 15 actions. Web page: https://docs.lodol.com/docs/integrations/browserbase

## Actions

### Check a browsing task

Read a task back. While it is still working this says how far it has got; once it has finished it carries what the browser found. Check 'is_finished' to know which you have.

**Inputs**

- Task (`run_id`, text, required): The task's id, as given back by 'Start a browsing task'.

**Outputs**

- `agent_id` (text): The saved agent it ran, if any.
- `created_at` (text): When the task was asked for.
- `ended_at` (text): When it stopped.
- `failure_reason` (text): Why it failed, when it did.
- `is_finished` (true/false): True once the task has stopped, however it ended.
- `is_successful` (true/false): True only when the task finished its job.
- `result` (object): What the task found, once it has finished.
- `run_id` (text): The task's id.
- `session_id` (text): The browser session behind the task.
- `started_at` (text): When the browser started.
- `status` (text): Where the task got to.
- `task` (text): What the browser was asked to do.

**Example output**

```json
{
  "agent_id": null,
  "created_at": "2026-09-18T09:14:00.000Z",
  "ended_at": "2026-09-18T09:15:47.000Z",
  "failure_reason": null,
  "is_finished": true,
  "is_successful": true,
  "result": {
    "price": "$39 per month"
  },
  "run_id": "run_01JB8Z5W2QK9V7T3M4N6P8R0SD",
  "session_id": "sess_01JB8Z5W2QK9V7T3M4N6P8R0SE",
  "started_at": "2026-09-18T09:14:02.000Z",
  "status": "COMPLETED",
  "task": "Find the starting price on the Browserbase pricing page."
}
```

### Check your usage

How much browser time and proxy traffic a project has used. Put it on a schedule to catch a runaway script before the bill does.

**Inputs**

- Project (`project`, text): Leave empty if the account has only one project, which most do. Pick one when there are several.

**Outputs**

- `browser_minutes` (number): Minutes of browser time used.
- `project_id` (text): The project this covers.
- `project_name` (text): What that project is called.
- `proxy_bytes` (number): Bytes sent through the proxies.
- `proxy_gigabytes` (number): The same traffic in gigabytes.

**Example output**

```json
{
  "browser_minutes": 142,
  "project_id": "proj_01JB8Z5W2QK9V7T3M4N6P8R0SG",
  "project_name": "Default",
  "proxy_bytes": 5368709120,
  "proxy_gigabytes": 5.0
}
```

### Close a browser session

Ask a browser session to finish, so it stops costing browser time instead of running until it times out. Use it on a browser that 'List browser sessions' shows still open.

**Inputs**

- Browser session (`session_id`, text, required): The session's id, as given back by 'List browser sessions' or by a finished task.

**Outputs**

- `created_at` (text): When it was asked for.
- `ended_at` (text): When it closed.
- `expires_at` (text): When it will close on its own.
- `is_running` (true/false): True while the browser is still open and being charged for.
- `keep_alive` (true/false): True when it stays open after the code disconnects.
- `project_id` (text): The project it belongs to.
- `proxy_bytes` (number): Bytes it sent through the proxies.
- `region` (text): Where in the world it is running.
- `session_id` (text): The browser session's id.
- `started_at` (text): When it opened.
- `status` (text): Where the browser got to.

**Example output**

```json
{
  "created_at": "2026-09-18T09:14:00.000Z",
  "ended_at": "2026-09-18T09:16:00.000Z",
  "expires_at": "2026-09-18T10:14:00.000Z",
  "is_running": false,
  "keep_alive": false,
  "project_id": "proj_01JB8Z5W2QK9V7T3M4N6P8R0SG",
  "proxy_bytes": 0,
  "region": "us-west-2",
  "session_id": "sess_01JB8Z5W2QK9V7T3M4N6P8R0SE",
  "started_at": "2026-09-18T09:14:02.000Z",
  "status": "COMPLETED"
}
```

### Delete a saved agent

Permanently delete a saved agent. Tasks that already ran under it keep their results, and deleting an agent that has already gone does nothing.

**Inputs**

- Agent (`agent_id`, text, required): Pick a saved agent. An agent made by an earlier step in this workflow is not in the list yet, so use its id from that step instead.

**Outputs**

- `agent_id` (text): The agent that was deleted.
- `deleted` (true/false): Always true once the delete went through.

**Example output**

```json
{
  "agent_id": "agent_01JB8Z5W2QK9V7T3M4N6P8R0SF",
  "deleted": true
}
```

### List browser sessions

List the browser sessions on this account, including any left open by code outside Lodol, and count how many are open right now and still costing browser time.

**Inputs**

- Only browsers that are (`status`, text): Narrow the list to one state. Leave empty for all of them. One of: `PENDING` (Starting up), `RUNNING` (Open now), `ERROR` (Ended with an error), `TIMED_OUT` (Ran out of time), `COMPLETED` (Closed).

**Outputs**

- `browser_count` (number): How many came back.
- `browsers` (list): The matching browser sessions.
- `running_count` (number): How many of them are still open.

**Example output**

```json
{
  "browser_count": 1,
  "browsers": [
    {
      "created_at": "2026-09-18T09:14:00.000Z",
      "ended_at": null,
      "expires_at": "2026-09-18T10:14:00.000Z",
      "is_running": true,
      "keep_alive": false,
      "project_id": "proj_01JB8Z5W2QK9V7T3M4N6P8R0SG",
      "proxy_bytes": 0,
      "region": "us-west-2",
      "session_id": "sess_01JB8Z5W2QK9V7T3M4N6P8R0SE",
      "started_at": "2026-09-18T09:14:02.000Z",
      "status": "RUNNING"
    }
  ],
  "running_count": 1
}
```

### List browsing tasks

List the browsing tasks this account has run, with where each one got to and what it found.

**Inputs**

- Only tasks that are (`status`, text): Narrow the list to one state. Leave empty for all of them. One of: `PENDING` (Waiting to start), `RUNNING` (Running now), `COMPLETED` (Finished), `FAILED`, `STOPPED` (Stopped by hand), `TIMED_OUT` (Ran out of time).
- Only tasks that ran (`agent_id`, text): Narrow the list to one saved agent. An agent made by an earlier step in this workflow is not in the list yet, so use its id from that step instead.
- Started on or after (`started_after`, date and time): Only tasks asked for at or after this moment.
- Started on or before (`started_before`, date and time): Only tasks asked for at or before this moment.
- How many tasks (`limit`, number): The most to return, up to 1,000. From 1 to 1000. Default: `20`.

**Outputs**

- `task_count` (number): How many tasks came back.
- `tasks` (list): The matching tasks.

**Example output**

```json
{
  "task_count": 1,
  "tasks": [
    {
      "agent_id": null,
      "created_at": "2026-09-18T09:14:00.000Z",
      "ended_at": "2026-09-18T09:15:47.000Z",
      "failure_reason": null,
      "is_finished": true,
      "is_successful": true,
      "result": {
        "price": "$39 per month"
      },
      "run_id": "run_01JB8Z5W2QK9V7T3M4N6P8R0SD",
      "session_id": "sess_01JB8Z5W2QK9V7T3M4N6P8R0SE",
      "started_at": "2026-09-18T09:14:02.000Z",
      "status": "COMPLETED",
      "task": "Find the starting price on the Browserbase pricing page."
    }
  ]
}
```

### List saved agents

List the saved agents on this account, with the standing instructions each one carries.

**Inputs**

- Saved on or after (`created_after`, date and time): Only agents saved at or after this moment.
- Saved on or before (`created_before`, date and time): Only agents saved at or before this moment.
- How many agents (`limit`, number): The most to return, up to 1,000. From 1 to 1000. Default: `20`.

**Outputs**

- `agent_count` (number): How many agents came back.
- `agents` (list): The saved agents.

**Example output**

```json
{
  "agent_count": 1,
  "agents": [
    {
      "agent_id": "agent_01JB8Z5W2QK9V7T3M4N6P8R0SF",
      "answer_shape": {
        "properties": {
          "invoice_total": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "created_at": "2026-09-01T11:00:00.000Z",
      "instructions": "Always download the PDF invoice rather than the summary page.",
      "name": "Supplier portal",
      "updated_at": "2026-09-01T11:00:00.000Z"
    }
  ]
}
```

### Pull details out of a web page

Fetch a page and pick named details out of it, so a later step gets tidy fields instead of a wall of text. Name what you want and Browserbase reads the page for it. It does not run the page's scripts and cannot read a PDF this way, so use 'Start a browsing task' for either.

**Inputs**

- Page address (`url`, text, required): The address of the page to read, starting with https://.
- Details to find (`details`, object, required): Name each detail and say what it is, for example 'price' and 'The price of the cheapest plan'. Each one comes back under the name you gave it.

**Outputs**

- `details` (object): The details found, under the names you gave.
- `is_ok` (true/false): True when the site answered normally.
- `status_code` (number): What the site answered with, such as 200 or 404.
- `url` (text): The page that was read.

**Example output**

```json
{
  "details": {
    "plan": "Starter",
    "price": "$39 per month"
  },
  "is_ok": true,
  "status_code": 200,
  "url": "https://www.browserbase.com/pricing"
}
```

### Read a web page

Fetch a page through Browserbase and bring back what it says, as readable text or as its HTML. The request carries a real browser's fingerprint, so a site that turns away a plain request will often answer this one. The page is fetched rather than opened, so for a page that only fills itself in once its scripts have run, use 'Start a browsing task' instead.

**Inputs**

- Page address (`url`, text, required): The address of the page to read, starting with https://.
- What to bring back (`format`, text): Readable text is right for almost everything: it is the page with the menus and markup stripped out. Browserbase charges the conversion at a higher rate than a plain fetch, so choose the HTML when a later step wants the markup anyway. One of: `markdown` (Readable text, ready for a later step), `raw` (The page's HTML, exactly as it was sent). Default: `markdown`.
- Follow redirects (`follow_redirects`, true/false): Keep going when the address forwards somewhere else. Turn this off to see the forwarding response itself. Default: `true`.

**Outputs**

- `content` (text): The page, as text or as HTML.
- `content_type` (text): What kind of thing the page is.
- `is_ok` (true/false): True when the site answered normally.
- `status_code` (number): What the site answered with, such as 200 or 404.
- `url` (text): The page that was read.

**Example output**

```json
{
  "content": "# Pricing\n\nStarter: $39 per month...",
  "content_type": "text/html; charset=utf-8",
  "is_ok": true,
  "status_code": 200,
  "url": "https://www.browserbase.com/pricing"
}
```

### Save an agent

Save a set of standing instructions that browsing tasks can run under, so the same rules do not have to be repeated in every task. Use it for the things that are always true of a site: where to sign in, what to avoid, what a good answer looks like.

**Inputs**

- Name (`name`, text, required): What to call this agent, so you can recognise it later, such as 'Supplier portal'.
- Standing instructions (`instructions`, text): What every task run under this agent should always do, such as 'Always download the PDF invoice rather than the summary page'.
- What the answer should contain (`answer_shape`, object): Name each thing the answer should carry and say what it is, for example 'price' and 'The total including delivery'. Leave it empty and the answer comes back as written text.

**Outputs**

- `agent_id` (text): The agent's id.
- `answer_shape` (object): The shape its answers come back in, if one was set.
- `created_at` (text): When it was saved.
- `instructions` (text): The standing instructions every task using it follows.
- `name` (text): What the agent is called.
- `updated_at` (text): When it last changed.

**Example output**

```json
{
  "agent_id": "agent_01JB8Z5W2QK9V7T3M4N6P8R0SF",
  "answer_shape": {
    "properties": {
      "invoice_total": {
        "type": "string"
      }
    },
    "type": "object"
  },
  "created_at": "2026-09-01T11:00:00.000Z",
  "instructions": "Always download the PDF invoice rather than the summary page.",
  "name": "Supplier portal",
  "updated_at": "2026-09-01T11:00:00.000Z"
}
```

### Search the web

Search the web and get back ranked results with their titles, addresses and publication dates. Pair it with 'Read a web page' to read the ones worth reading.

**Inputs**

- What to look for (`query`, text, required): What to search for, in plain language, up to 200 characters.
- How many results (`number_of_results`, number): How many results to return, up to 25. From 1 to 25. Default: `10`.

**Outputs**

- `query` (text): The search that was run.
- `result_count` (number): How many results came back.
- `results` (list): The results, best first.

**Example output**

```json
{
  "query": "browserbase pricing",
  "result_count": 1,
  "results": [
    {
      "id": "res_01JB8Z5W2QK9V7T3M4N6P8R0SH",
      "publishedDate": "2026-05-04T00:00:00.000Z",
      "title": "Pricing | Browserbase",
      "url": "https://www.browserbase.com/pricing"
    }
  ]
}
```

### See what a browsing task did

Read back the steps a task took, in order: the pages it opened, what it clicked and what it said along the way. Use it when a task did not come back with what you expected.

**Inputs**

- Task (`run_id`, text, required): The task's id, as given back by 'Start a browsing task'.
- How many steps (`limit`, number): How many of the most recent steps to bring back, up to 500. The newest is last. From 1 to 500. Default: `50`.

**Outputs**

- `step_count` (number): How many steps came back.
- `steps` (list): What the browser did, oldest first.
- `total_step_count` (number): How many steps the task took in total.

**Example output**

```json
{
  "step_count": 2,
  "steps": [
    {
      "action": "Used goto",
      "at": "2026-09-18T09:14:05.000Z",
      "detail": "{\"url\": \"https://www.browserbase.com/pricing\"}"
    },
    {
      "action": "Said",
      "at": "2026-09-18T09:15:44.000Z",
      "detail": "The cheapest plan is $39 per month."
    }
  ],
  "total_step_count": 2
}
```

### Start a browsing task

Describe a job in plain language and a cloud browser does it: searching, opening pages, clicking, typing and reading. The browser works in the background, so this step hands back a task id straight away. Follow it with a Wait step and 'Check a browsing task' to collect what it found.

**Inputs**

- What the browser should do (`task`, text, required): Say where to go and what to bring back. Be specific: the browser follows this the way a new colleague would.
- Saved agent (`agent_id`, text): Run this task under a saved agent, so it follows that agent's standing instructions. Leave empty for a one-off task. An agent made by an earlier step in this workflow is not in the list yet, so use its id from that step instead.
- Details the task needs (`details`, object): Values the browser should use but that should stay out of the task text, such as a username or a password. Refer to one in the task as %name%. They are sent for this run only and are not kept by Browserbase.
- What the answer should contain (`answer_shape`, object): Name each thing the answer should carry and say what it is, for example 'price' and 'The total including delivery'. Leave it empty and the answer comes back as written text.

**Outputs**

- `agent_id` (text): The saved agent it ran, if any.
- `created_at` (text): When the task was asked for.
- `ended_at` (text): When it stopped.
- `failure_reason` (text): Why it failed, when it did.
- `is_finished` (true/false): True once the task has stopped, however it ended.
- `is_successful` (true/false): True only when the task finished its job.
- `result` (object): What the task found, once it has finished.
- `run_id` (text): The task's id.
- `session_id` (text): The browser session behind the task.
- `started_at` (text): When the browser started.
- `status` (text): Where the task got to.
- `task` (text): What the browser was asked to do.

**Example output**

```json
{
  "agent_id": null,
  "created_at": "2026-09-18T09:14:00.000Z",
  "ended_at": null,
  "failure_reason": null,
  "is_finished": false,
  "is_successful": false,
  "result": null,
  "run_id": "run_01JB8Z5W2QK9V7T3M4N6P8R0SD",
  "session_id": "sess_01JB8Z5W2QK9V7T3M4N6P8R0SE",
  "started_at": null,
  "status": "PENDING",
  "task": "Find the starting price on the Browserbase pricing page."
}
```

### Stop a browsing task

Ask a task that is still running to wind down and close its browser. A task that has already finished cannot be stopped.

**Inputs**

- Task (`run_id`, text, required): The task's id, as given back by 'Start a browsing task'.

**Outputs**

- `agent_id` (text): The saved agent it ran, if any.
- `created_at` (text): When the task was asked for.
- `ended_at` (text): When it stopped.
- `failure_reason` (text): Why it failed, when it did.
- `is_finished` (true/false): True once the task has stopped, however it ended.
- `is_successful` (true/false): True only when the task finished its job.
- `result` (object): What the task found, once it has finished.
- `run_id` (text): The task's id.
- `session_id` (text): The browser session behind the task.
- `started_at` (text): When the browser started.
- `status` (text): Where the task got to.
- `task` (text): What the browser was asked to do.

**Example output**

```json
{
  "agent_id": null,
  "created_at": "2026-09-18T09:14:00.000Z",
  "ended_at": "2026-09-18T09:15:47.000Z",
  "failure_reason": null,
  "is_finished": true,
  "is_successful": false,
  "result": {
    "price": "$39 per month"
  },
  "run_id": "run_01JB8Z5W2QK9V7T3M4N6P8R0SD",
  "session_id": "sess_01JB8Z5W2QK9V7T3M4N6P8R0SE",
  "started_at": "2026-09-18T09:14:02.000Z",
  "status": "STOPPED",
  "task": "Find the starting price on the Browserbase pricing page."
}
```

### Update a saved agent

Change a saved agent's name, its standing instructions or the shape of its answers. Anything left empty stays as it was. Tasks already running are unaffected.

**Inputs**

- Agent (`agent_id`, text, required): Pick a saved agent. An agent made by an earlier step in this workflow is not in the list yet, so use its id from that step instead.
- New name (`name`, text): Leave empty to keep the name it has.
- New standing instructions (`instructions`, text): Replaces the instructions the agent has now. Leave empty to keep them.
- New answer shape (`answer_shape`, object): Name each thing the answer should carry and say what it is. Leave empty to keep the shape it has.

**Outputs**

- `agent_id` (text): The agent's id.
- `answer_shape` (object): The shape its answers come back in, if one was set.
- `created_at` (text): When it was saved.
- `instructions` (text): The standing instructions every task using it follows.
- `name` (text): What the agent is called.
- `updated_at` (text): When it last changed.

**Example output**

```json
{
  "agent_id": "agent_01JB8Z5W2QK9V7T3M4N6P8R0SF",
  "answer_shape": {
    "properties": {
      "invoice_total": {
        "type": "string"
      }
    },
    "type": "object"
  },
  "created_at": "2026-09-01T11:00:00.000Z",
  "instructions": "Always download the PDF invoice rather than the summary page.",
  "name": "Supplier portal (invoices)",
  "updated_at": "2026-09-18T09:20:00.000Z"
}
```