Skip to main content
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.
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

Structured output

Pass a schema to get validated, typed data back.
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)

Streaming steps

Use async for to yield steps as the agent works.
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

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.
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)
Presigned URLs expire after 120 seconds. Max file size: 10 MB.

Download task output files

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

Key parameters

ParameterTypeDescription
taskstrWhat you want the agent to do. 1-50,000 characters.
llmstrModel override. Default: Browser Use 2.0. See Models & Pricing.
output_schema / schemaPydantic / ZodSchema for structured output.
session_idstrReuse an existing session. Omit for auto-session.
start_urlstrInitial page URL. Saves steps — send the agent directly there.
secretsdictDomain-specific credentials. See Authentication.
allowed_domainslist[str]Restrict agent to these domains only.
session_settingsSessionSettingsProxy, profile, browser config. See Sessions.
flash_modeboolFaster but less careful navigation.
thinkingboolEnable extended reasoning.
visionbool | strEnable screenshots for the agent.
highlight_elementsboolHighlight interactive elements on the page.
system_prompt_extensionstrAppend custom instructions to the system prompt.
judgeboolEnable quality judge to verify output.
skill_idslist[str]Skills the agent can use during the task.
op_vault_idstr1Password vault ID for auto-fill credentials and 2FA. See Authentication.
metadatadict[str, str]Custom metadata attached to the task.