BU Agent API (v3 — Experimental)

Next-generation agent API. Session-based, token-based billing, workspaces, message history.

Table of Contents

• Authentication
• SDK Setup
• run() — Execute a Task
• REST Endpoints
• Sessions
• Messages
• Files
• Workspaces
• Polling & Terminal Statuses
• Error Handling
• Session Statuses & Enums
• Response Schemas

Authentication

• Header: X-Browser-Use-API-Key: <your-key>
• Base URL: https://api.browser-use.com/api/v3
• Get key: https://cloud.browser-use.com/new-api-key

Same package as v2, different import path:

SDK Setup

# Python (async — recommended)
from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()  # Uses BROWSER_USE_API_KEY env var

# Python (sync)
from browser_use_sdk.v3 import BrowserUse
client = BrowserUse()

// TypeScript
import { BrowserUse } from "browser-use-sdk/v3";
const client = new BrowserUse();

Constructor: api_key, base_url, timeout (HTTP request timeout, not polling).

run() — Execute a Task

result = await client.run("Find the top HN post")
print(result.output)    # str
print(result.id)        # session UUID
print(result.status)    # e.g. "idle"
print(result.total_cost_usd)  # cost breakdown

Parameters

Structured Output

from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float

result = await client.run("Get product info", output_schema=Product)
print(result.output)  # Product instance

SessionResult Fields

REST Endpoints

All 16 endpoints in the v3 API:

Sessions

POST /sessions — Create session and/or dispatch task. Body: { task?, model?, session_id?, keep_alive?, max_cost_usd?, profile_id?, proxy_country_code?, output_schema? (JSON Schema dict) } Response: SessionView

GET /sessions — List sessions. Query: page? (int), page_size? (int) Response: { sessions: SessionView[], total, page, page_size }

GET /sessions/{id} — Get session details (includes cost breakdown). Response: SessionView

DELETE /sessions/{id} — Delete session. Response: 204

POST /sessions/{id}/stop — Stop session or task. Query: strategy? — "session" (default, destroy sandbox) or "task" (stop task only, keep session alive) Response: 200

Messages

GET /sessions/{id}/messages — Cursor-paginated message history.

Response: { messages: [{ id, role: "user"|"assistant", data: string, timestamp }], next_cursor?, has_more: boolean }

Files

GET /sessions/{id}/files — List files in session workspace.

Response: { files: [{ path, size, last_modified, url? }], next_cursor?, has_more }

POST /sessions/{id}/files/upload — Get presigned upload URLs. Body: { files: [{ name: string, content_type: string }] } Response: { files: [{ name, upload_url, path }] }

Upload via PUT to upload_url with matching Content-Type header. Max 10 files per batch. Presigned URLs expire in 120 seconds. Max file size: 10 MB.

Workspaces

POST /workspaces — Create persistent workspace. Body: { name?: string, metadata?: object } Response: WorkspaceView

GET /workspaces — List workspaces. Query: page?, page_size? Response: { items: WorkspaceView[], total, page, page_size }

GET /workspaces/{id} — Get workspace details.

PATCH /workspaces/{id} — Update workspace. Body: { name?: string, metadata?: object }

DELETE /workspaces/{id} — Delete workspace and all files (irreversible).

GET /workspaces/{id}/files — List workspace files. Query: include_urls?, prefix?, limit?, cursor? Response: same format as session files

GET /workspaces/{id}/size — Storage usage. Response: { size_bytes: int, quota_bytes: int }

POST /workspaces/{id}/files/upload — Upload files to workspace. Same format as session file upload.

Polling & Terminal Statuses

run() polls automatically:

• Interval: 2 seconds
• Timeout: 300 seconds (5 minutes) — raises TimeoutError if exceeded
• Terminal statuses: idle, stopped, timed_out, error

Stop Strategies

await client.sessions.stop(session_id, strategy="task")   # keep session
await client.sessions.stop(session_id, strategy="session") # destroy

Error Handling

from browser_use_sdk.v3 import AsyncBrowserUse, BrowserUseError

try:
    result = await client.run("Do something")
except TimeoutError:
    print("Polling timed out (5 min default)")
except BrowserUseError as e:
    print(f"API error: {e}")

Session Statuses & Enums

Models: bu-mini (default, faster/cheaper), bu-max (more capable)

Response Schemas

SessionView (v3): id, status, model, title?, live_url, output?, profile_id?, proxy_country_code?, max_cost_usd?, total_input_tokens, total_output_tokens, llm_cost_usd, proxy_cost_usd, proxy_used_mb, total_cost_usd, created_at, updated_at

MessageView: id, role ("user"|"assistant"), data (string), timestamp

FileInfo: path, size, last_modified, url?

WorkspaceView: id, name?, metadata?, created_at, updated_at, size_bytes?

Key concepts:

• Autonomous execution — agent decides how many steps (no max_steps param)
• Cost control — max_cost_usd caps spending; check total_cost_usd on result
• Integrations — agent auto-discovers third-party services (email, Slack, calendars)
• File I/O — upload before task, download from workspace after. Max 10 files per batch, download URLs expire in 60s