Tasks

Run AI browser automation tasks with structured output, configurable models, real-time streaming, cost controls, and natural language instructions.

A task is the core primitive. Describe what you want in plain text, the agent browses the web and returns the result.

run()

Runs the task and returns a TaskResult with typed output.

Python

from browser_use_sdk import AsyncBrowserUse

client = AsyncBrowserUse()
result = await client.run("What is the current price of Bitcoin?")
print(result.output)   # "Bitcoin is currently $67,432..."
print(result.id)       # task ID
print(result.status)   # TaskStatus.FINISHED
print(result.steps)    # list of TaskStepView

import { BrowserUse } from "browser-use-sdk";

const client = new BrowserUse();
const result = await client.run("What is the current price of Bitcoin?");
console.log(result.output);  // "Bitcoin is currently $67,432..."
console.log(result.id);      // task ID
console.log(result.status);  // "finished"
console.log(result.steps);   // TaskStepView[]

Structured output

Pass a schema to get validated, typed data back.

Python

from browser_use_sdk import AsyncBrowserUse
from pydantic import BaseModel

class Stock(BaseModel):
    ticker: str
    price: float
    change_pct: float

client = AsyncBrowserUse()
result = await client.run(
    "Get the current stock price of NVDA from Yahoo Finance",
    output_schema=Stock,
)
print(result.output)  # Stock(ticker='NVDA', price=135.40, change_pct=2.3)

import { BrowserUse } from "browser-use-sdk";
import { z } from "zod";

const Stock = z.object({
  ticker: z.string(),
  price: z.number(),
  changePct: z.number(),
});

const client = new BrowserUse();
const result = await client.run(
  "Get the current stock price of NVDA from Yahoo Finance",
  { schema: Stock },
);
console.log(result.output);  // { ticker: "NVDA", price: 135.40, changePct: 2.3 }

Streaming steps

Use async for to yield steps as the agent works.

Python

from browser_use_sdk import AsyncBrowserUse

client = AsyncBrowserUse()
run = client.run("Find the cheapest flight from NYC to London on Google Flights")
async for step in run:
    print(f"Step {step.number}: {step.next_goal}")
    print(f"  URL: {step.url}")

print(run.result.output)  # final result after iteration

import { BrowserUse } from "browser-use-sdk";

const client = new BrowserUse();
const run = client.run("Find the cheapest flight from NYC to London on Google Flights");
for await (const step of run) {
  console.log(`Step ${step.number}: ${step.nextGoal}`);
  console.log(`  URL: ${step.url}`);
}

console.log(run.result?.output);  // final result after iteration

Message streaming (v3)

In the BU Agent API, use sessions.messages() to poll the agent’s message history while a task runs. This gives you the full conversation — user messages, assistant reasoning, and tool calls.

Python

import asyncio
from browser_use_sdk.v3 import AsyncBrowserUse

client = AsyncBrowserUse()

session = await client.sessions.create("Find the top story on Hacker News")
session_id = str(session.id)

seen = set()
while True:
    s = await client.sessions.get(session_id)
    msgs = await client.sessions.messages(session_id, limit=100)

    for m in msgs.messages:
        if str(m.id) not in seen:
            seen.add(str(m.id))
            print(f"[{m.role}] {m.data[:200]}")

    if s.status.value in ("idle", "stopped", "error", "timed_out"):
        print(f"\nDone — {s.output}")
        break
    await asyncio.sleep(2)

import { BrowserUse } from "browser-use-sdk/v3";

const client = new BrowserUse();

const session = await client.sessions.create({
  task: "Find the top story on Hacker News",
});
const sessionId = session.id;

const seen = new Set<string>();
while (true) {
  const s = await client.sessions.get(sessionId);
  const msgs = await client.sessions.messages(sessionId, { limit: 100 });

  for (const m of msgs.messages) {
    if (!seen.has(m.id)) {
      seen.add(m.id);
      console.log(`[${m.role}] ${m.data.slice(0, 200)}`);
    }
  }

  if (["idle", "stopped", "error", "timed_out"].includes(s.status)) {
    console.log(`\nDone — ${s.output}`);
    break;
  }
  await new Promise((r) => setTimeout(r, 2000));
}

Use after and before cursors for pagination through large message histories.

Files

Upload images, PDFs, documents, and text files (10 MB max) to sessions, and download output files from completed tasks.

Upload a file

Get a presigned URL, then upload via PUT.

Python

import httpx
from browser_use_sdk import AsyncBrowserUse

client = AsyncBrowserUse()
session = await client.sessions.create()

upload = await client.files.session_url(
    session.id,
    file_name="input.pdf",
    content_type="application/pdf",
    size_bytes=1024,
)

with open("input.pdf", "rb") as f:
    async with httpx.AsyncClient() as http:
        await http.put(upload.presigned_url, content=f.read(), headers={"Content-Type": "application/pdf"})

result = await client.run("Summarize the uploaded PDF", session_id=session.id)

import { BrowserUse } from "browser-use-sdk";
import { readFileSync } from "fs";

const client = new BrowserUse();
const session = await client.sessions.create();

const upload = await client.files.sessionUrl(session.id, {
  fileName: "input.pdf",
  contentType: "application/pdf",
  sizeBytes: 1024,
});

await fetch(upload.presignedUrl, {
  method: "PUT",
  body: readFileSync("input.pdf"),
  headers: { "Content-Type": "application/pdf" },
});

const result = await client.run("Summarize the uploaded PDF", { sessionId: session.id });

Presigned URLs expire after 120 seconds. Max file size: 10 MB.

Download task output files

Python

result = await client.tasks.get(task_id)
for file in result.output_files:
    output = await client.files.task_output(task_id, file.id)
    print(output.presigned_url)  # download URL

const result = await client.tasks.get(taskId);
for (const file of result.outputFiles) {
  const output = await client.files.taskOutput(taskId, file.id);
  console.log(output.presignedUrl);
}

Key parameters

Parameter	Type	Description
task	str	What you want the agent to do. 1-50,000 characters.
llm	str	Model override. Default: Browser Use 2.0. See Models & Pricing.
output_schema / schema	Pydantic / Zod	Schema for structured output.
session_id	str	Reuse an existing session. Omit for auto-session.
start_url	str	Initial page URL. Saves steps — send the agent directly there.
secrets	dict	Domain-specific credentials. See Authentication.
allowed_domains	list[str]	Restrict agent to these domains only.
session_settings	SessionSettings	Proxy, profile, browser config. See Sessions.
flash_mode	bool	Faster but less careful navigation.
thinking	bool	Enable extended reasoning.
vision	bool | str	Enable screenshots for the agent.
highlight_elements	bool	Highlight interactive elements on the page.
system_prompt_extension	str	Append custom instructions to the system prompt.
judge	bool	Enable quality judge to verify output.
skill_ids	list[str]	Skills the agent can use during the task.
op_vault_id	str	1Password vault ID for auto-fill credentials and 2FA. See Authentication.
metadata	dict[str, str]	Custom metadata attached to the task.