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.

Actions

Action	What it does
Check a browsing task	Read a task back.
Check your usage	How much browser time and proxy traffic a project has used.
Close a browser session	Ask a browser session to finish, so it stops costing browser time instead of running until it times out.
Delete a saved agent	Permanently delete a saved agent.
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.
List browsing tasks	List the browsing tasks this account has run, with where each one got to and what it found.
List saved agents	List the saved agents on this account, with the standing instructions each one carries.
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.
Read a web page	Fetch a page through Browserbase and bring back what it says, as readable text or as its HTML.
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.
Search the web	Search the web and get back ranked results with their titles, addresses and publication dates.
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.
Start a browsing task	Describe a job in plain language and a cloud browser does it: searching, opening pages, clicking, typing and reading.
Stop a browsing task	Ask a task that is still running to wind down and close its browser.
Update a saved agent	Change a saved agent's name, its standing instructions or the shape of its answers.

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

Taskrun_idtextRequired: The task's id, as given back by 'Start a browsing task'.

Outputs

agent_idtext: The saved agent it ran, if any.
created_attext: When the task was asked for.
ended_attext: When it stopped.
failure_reasontext: Why it failed, when it did.
is_finishedtrue/false: True once the task has stopped, however it ended.
is_successfultrue/false: True only when the task finished its job.
resultobject: What the task found, once it has finished.
run_idtext: The task's id.
session_idtext: The browser session behind the task.
started_attext: When the browser started.
statustext: Where the task got to.
tasktext: What the browser was asked to do.

Example output

{
  "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

Projectprojecttext: Leave empty if the account has only one project, which most do. Pick one when there are several.

Outputs

browser_minutesnumber: Minutes of browser time used.
project_idtext: The project this covers.
project_nametext: What that project is called.
proxy_bytesnumber: Bytes sent through the proxies.
proxy_gigabytesnumber: The same traffic in gigabytes.

Example output

{
  "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 sessionsession_idtextRequired: The session's id, as given back by 'List browser sessions' or by a finished task.

Outputs

created_attext: When it was asked for.
ended_attext: When it closed.
expires_attext: When it will close on its own.
is_runningtrue/false: True while the browser is still open and being charged for.
keep_alivetrue/false: True when it stays open after the code disconnects.
project_idtext: The project it belongs to.
proxy_bytesnumber: Bytes it sent through the proxies.
regiontext: Where in the world it is running.
session_idtext: The browser session's id.
started_attext: When it opened.
statustext: Where the browser got to.

Example output

{
  "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

Agentagent_idtextRequired: 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_idtext: The agent that was deleted.
deletedtrue/false: Always true once the delete went through.

Example output

{
  "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 arestatustext: 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_countnumber: How many came back.
browserslist: The matching browser sessions.
running_countnumber: How many of them are still open.

Example output

{
  "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 arestatustext: 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 ranagent_idtext: 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 afterstarted_afterdate and time: Only tasks asked for at or after this moment.
Started on or beforestarted_beforedate and time: Only tasks asked for at or before this moment.
How many taskslimitnumber: The most to return, up to 1,000.From 1 to 1000. Default: 20.

Outputs

task_countnumber: How many tasks came back.
taskslist: The matching tasks.

Example output

{
  "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 aftercreated_afterdate and time: Only agents saved at or after this moment.
Saved on or beforecreated_beforedate and time: Only agents saved at or before this moment.
How many agentslimitnumber: The most to return, up to 1,000.From 1 to 1000. Default: 20.

Outputs

agent_countnumber: How many agents came back.
agentslist: The saved agents.

Example output

{
  "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 addressurltextRequired: The address of the page to read, starting with https://.
Details to finddetailsobjectRequired: 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

detailsobject: The details found, under the names you gave.
is_oktrue/false: True when the site answered normally.
status_codenumber: What the site answered with, such as 200 or 404.
urltext: The page that was read.

Example output

{
  "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 addressurltextRequired: The address of the page to read, starting with https://.
What to bring backformattext: 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 redirectsfollow_redirectstrue/false: Keep going when the address forwards somewhere else. Turn this off to see the forwarding response itself.Default: true.

Outputs

contenttext: The page, as text or as HTML.
content_typetext: What kind of thing the page is.
is_oktrue/false: True when the site answered normally.
status_codenumber: What the site answered with, such as 200 or 404.
urltext: The page that was read.

Example output

{
  "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

NamenametextRequired: What to call this agent, so you can recognise it later, such as 'Supplier portal'.
Standing instructionsinstructionstext: 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 containanswer_shapeobject: 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_idtext: The agent's id.
answer_shapeobject: The shape its answers come back in, if one was set.
created_attext: When it was saved.
instructionstext: The standing instructions every task using it follows.
nametext: What the agent is called.
updated_attext: When it last changed.

Example output

{
  "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 forquerytextRequired: What to search for, in plain language, up to 200 characters.
How many resultsnumber_of_resultsnumber: How many results to return, up to 25.From 1 to 25. Default: 10.

Outputs

querytext: The search that was run.
result_countnumber: How many results came back.
resultslist: The results, best first.

Example output

{
  "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

Taskrun_idtextRequired: The task's id, as given back by 'Start a browsing task'.
How many stepslimitnumber: 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_countnumber: How many steps came back.
stepslist: What the browser did, oldest first.
total_step_countnumber: How many steps the task took in total.

Example output

{
  "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 dotasktextRequired: Say where to go and what to bring back. Be specific: the browser follows this the way a new colleague would.
Saved agentagent_idtext: 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 needsdetailsobject: 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 containanswer_shapeobject: 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_idtext: The saved agent it ran, if any.
created_attext: When the task was asked for.
ended_attext: When it stopped.
failure_reasontext: Why it failed, when it did.
is_finishedtrue/false: True once the task has stopped, however it ended.
is_successfultrue/false: True only when the task finished its job.
resultobject: What the task found, once it has finished.
run_idtext: The task's id.
session_idtext: The browser session behind the task.
started_attext: When the browser started.
statustext: Where the task got to.
tasktext: What the browser was asked to do.

Example output

{
  "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

Taskrun_idtextRequired: The task's id, as given back by 'Start a browsing task'.

Outputs

agent_idtext: The saved agent it ran, if any.
created_attext: When the task was asked for.
ended_attext: When it stopped.
failure_reasontext: Why it failed, when it did.
is_finishedtrue/false: True once the task has stopped, however it ended.
is_successfultrue/false: True only when the task finished its job.
resultobject: What the task found, once it has finished.
run_idtext: The task's id.
session_idtext: The browser session behind the task.
started_attext: When the browser started.
statustext: Where the task got to.
tasktext: What the browser was asked to do.

Example output

{
  "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

Agentagent_idtextRequired: 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 namenametext: Leave empty to keep the name it has.
New standing instructionsinstructionstext: Replaces the instructions the agent has now. Leave empty to keep them.
New answer shapeanswer_shapeobject: Name each thing the answer should carry and say what it is. Leave empty to keep the shape it has.

Outputs

agent_idtext: The agent's id.
answer_shapeobject: The shape its answers come back in, if one was set.
created_attext: When it was saved.
instructionstext: The standing instructions every task using it follows.
nametext: What the agent is called.
updated_attext: When it last changed.

Example output

{
  "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"
}

ActionsCopy Anchor Link

Check a browsing taskCopy Anchor Link

Inputs

Outputs

Check your usageCopy Anchor Link

Inputs

Outputs

Close a browser sessionCopy Anchor Link

Inputs

Outputs

Delete a saved agentCopy Anchor Link

Inputs

Outputs

List browser sessionsCopy Anchor Link

Inputs

Outputs

List browsing tasksCopy Anchor Link

Inputs

Outputs

List saved agentsCopy Anchor Link

Inputs

Outputs

Pull details out of a web pageCopy Anchor Link

Inputs

Outputs

Read a web pageCopy Anchor Link

Inputs

Outputs

Save an agentCopy Anchor Link

Inputs

Outputs

Search the webCopy Anchor Link

Inputs

Outputs

See what a browsing task didCopy Anchor Link

Inputs

Outputs

Start a browsing taskCopy Anchor Link

Inputs

Outputs

Stop a browsing taskCopy Anchor Link

Inputs

Outputs

Update a saved agentCopy Anchor Link

Inputs

Outputs

On this page

Actions

Check a browsing task

Check your usage

Close a browser session

Delete a saved agent

List browser sessions

List browsing tasks

List saved agents

Pull details out of a web page

Read a web page

Save an agent

Search the web

See what a browsing task did

Start a browsing task

Stop a browsing task

Update a saved agent