Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
split cloud API reference into v2 and v3, add REST-first coverage
ShawnPana607c6c814e09
diff --git a/skills/browser-use-docs/SKILL.md b/skills/browser-use-docs/SKILL.mdindex c52c46fd8..52956e90d 100644--- a/skills/browser-use-docs/SKILL.md+++ b/skills/browser-use-docs/SKILL.md@@ -38,7 +38,8 @@ Read the relevant reference file based on what the user needs.| Topic | Read ||-------|------|| Setup, first task, pricing, FAQ | `references/cloud/quickstart.md` |-| REST endpoints (v2), SDK methods, v3, schemas | `references/cloud/api.md` |+| v2 REST API: all 30 endpoints, cURL examples, schemas | `references/cloud/api-v2.md` |+| v3 BU Agent API: sessions, messages, files, workspaces | `references/cloud/api-v3.md` || Sessions, profiles, auth strategies, 1Password | `references/cloud/sessions.md` || CDP direct access, Playwright/Puppeteer/Selenium | `references/cloud/browser-api.md` || Proxies, webhooks, workspaces, skills, MCP, live view | `references/cloud/features.md` |diff --git a/skills/browser-use-docs/references/cloud/api-v2.md b/skills/browser-use-docs/references/cloud/api-v2.mdnew file mode 100644index 000000000..107cd367e--- /dev/null+++ b/skills/browser-use-docs/references/cloud/api-v2.md@@ -0,0 +1,321 @@+# Cloud API v2 (Stable)++Full-featured REST API for tasks, sessions, browsers, profiles, skills, and marketplace.++## Table of Contents+- [Authentication](#authentication)+- [Common cURL Examples](#common-curl-examples)+- [Tasks](#tasks)+- [Sessions](#sessions)+- [Browsers (CDP)](#browsers-cdp)+- [Files](#files)+- [Profiles](#profiles)+- [Skills](#skills)+- [Marketplace](#marketplace)+- [Billing](#billing)+- [Pagination](#pagination)+- [Enums](#enums)+- [Response Schemas](#response-schemas)++---++## Authentication++- **Header:** `X-Browser-Use-API-Key: <your-key>`+- **Base URL:** `https://api.browser-use.com/api/v2`+- **Get key:** https://cloud.browser-use.com/new-api-key++All endpoints require the `X-Browser-Use-API-Key` header.++## Common cURL Examples++### Create a task++```bash+curl -X POST https://api.browser-use.com/api/v2/tasks \+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{"task": "Find the top Hacker News post and return title and URL"}'+```++Response: `{"id": "<task-id>", "sessionId": "<session-id>"}`++### Poll task status++```bash+curl https://api.browser-use.com/api/v2/tasks/<task-id>/status \+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"+```++### Get session live URL++```bash+curl https://api.browser-use.com/api/v2/sessions/<session-id> \+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY"+```++Response includes `liveUrl` — open it to watch the agent work.++### Create a CDP browser++```bash+curl -X POST https://api.browser-use.com/api/v2/browsers \+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{"proxyCountryCode": "us", "timeout": 30}'+```++Response includes `cdpUrl` (WebSocket) and `liveUrl`.++### Stop a session++```bash+curl -X PATCH https://api.browser-use.com/api/v2/sessions/<session-id> \+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{"action": "stop"}'+```++### Upload a file to a session++```bash+# 1. Get presigned URL+curl -X POST https://api.browser-use.com/api/v2/files/sessions/<session-id>/presigned-url \+ -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{"fileName": "input.pdf", "contentType": "application/pdf", "sizeBytes": 102400}'++# 2. Upload via PUT to the returned URL+curl -X PUT "<presigned-url>" \+ -H "Content-Type: application/pdf" \+ --data-binary @input.pdf+```++Presigned URLs expire after **120 seconds**. Max file size: **10 MB**.++---++## Tasks++**GET /tasks** — Paginated list with filtering.+Query: `pageSize?`, `pageNumber?`, `sessionId?` (uuid), `filterBy?` (TaskStatus), `after?` (datetime), `before?` (datetime)+Response: `{ items: TaskItemView[], totalItems, pageNumber, pageSize }`++**POST /tasks** — Create and run a task. Auto-creates session or uses existing.++| Param | Type | Required | Description |+|-------|------|----------|-------------|+| task | string | **yes** | Task prompt (1-50,000 chars) |+| llm | SupportedLLMs | no | Model (default: browser-use-llm) |+| startUrl | string | no | Initial URL (saves steps) |+| maxSteps | integer | no | Max agent steps (default: 100) |+| structuredOutput | string | no | JSON schema string |+| sessionId | uuid | no | Run in existing session |+| metadata | object | no | Key-value metadata (string values) |+| secrets | object | no | Domain-scoped credentials (string values) |+| allowedDomains | string[] | no | Restrict navigation |+| opVaultId | string | no | 1Password vault ID |+| highlightElements | boolean | no | Highlight interactive elements |+| flashMode | boolean | no | Fast mode (skip evaluation/thinking) |+| thinking | boolean | no | Extended reasoning |+| vision | boolean\|"auto" | no | Screenshot mode |+| systemPromptExtension | string | no | Append to system prompt |+| judge | boolean | no | Enable quality judge |+| skillIds | string[] | no | Skills to use during task |++Response (202): `{ id: uuid, sessionId: uuid }`+Errors: 400 (session busy/stopped), 404 (session not found), 422 (validation), 429 (rate limit)++**GET /tasks/{task_id}** — Detailed task info with steps and output files.+Response: TaskView++**GET /tasks/{task_id}/status** — Poll task status (lighter than full GET).+Response: `{ status: TaskStatus }`++**PATCH /tasks/{task_id}** — Control task execution.+Body: `{ action: TaskUpdateAction }` — `stop`, `pause`, `resume`, or `stop_task_and_session`+Response: TaskView. Errors: 404, 422.++**GET /tasks/{task_id}/logs** — Download URL for execution logs.+Response: `{ downloadUrl: string }`. Errors: 404, 500.++---++## Sessions++**GET /sessions** — Paginated list.+Query: `pageSize?`, `pageNumber?`, `filterBy?` (SessionStatus)++**POST /sessions** — Create a session.+Body: `{ profileId?: uuid, proxyCountryCode?: string, startUrl?: string }`+Response (201): SessionItemView. Errors: 404 (profile not found), 429 (too many concurrent).++**GET /sessions/{id}** — Session details with tasks and share URL.+Response: SessionView++**PATCH /sessions/{id}** — Stop session and all running tasks.+Body: `{ action: "stop" }`. Errors: 404, 422.++**POST /sessions/{id}/purge** — Purge session data.+Response: 200.++**GET /sessions/{id}/public-share** — Get share info.+Response: ShareView. Errors: 404.++**POST /sessions/{id}/public-share** — Create or return existing share.+Response (201): ShareView.++**DELETE /sessions/{id}/public-share** — Remove share.+Response: 204.++---++## Browsers (CDP)++**POST /browsers** — Create a CDP browser session.++| Param | Type | Required | Description |+|-------|------|----------|-------------|+| profileId | uuid | no | Browser profile |+| proxyCountryCode | string | no | Residential proxy (195+ countries) |+| timeout | integer | no | Session timeout in minutes (max 240) |+| browserScreenWidth | integer | no | Browser width in pixels |+| browserScreenHeight | integer | no | Browser height in pixels |+| customProxy | object | no | `{ host, port, username?, password? }` (HTTP or SOCKS5) |++**Pricing:** $0.05/hour. Billed upfront, proportional refund on stop. Ceil to nearest minute (min 1 min). Free: 15 min max. Paid: 4 hours max.++Response (201): BrowserSessionItemView (includes `cdpUrl` and `liveUrl`).+Errors: 403 (timeout exceeded for free), 404 (profile not found), 429 (too many concurrent).++**GET /browsers/{id}** — Browser session details.++**PATCH /browsers/{id}** — Stop browser (unused time refunded).+Body: `{ action: "stop" }`++---++## Files++**POST /files/sessions/{id}/presigned-url** — Get upload URL for session files.+Body: `{ fileName: string, contentType: UploadContentType, sizeBytes: integer }`+Response: `{ url: string, method: "POST", fields: {}, fileName: string, expiresIn: integer }`+Errors: 400 (unsupported type), 404, 500.++**POST /files/browsers/{id}/presigned-url** — Same for browser sessions.++**GET /files/tasks/{task_id}/output-files/{file_id}** — Download URL for task output.+Response: `{ id: uuid, fileName: string, downloadUrl: string }`+Errors: 404, 500.++**Upload flow:** Get presigned URL → PUT file with Content-Type header → URL expires in 120s → Max 10 MB.++---++## Profiles++**GET /profiles** — Paginated list. Query: `pageSize?`, `pageNumber?`++**POST /profiles** — Create profile (persistent cookies/localStorage between tasks).+Body: `{ name?: string }`. Response (201): ProfileView. Error: 402 (subscription needed).++**GET /profiles/{id}** — Profile details.++**DELETE /profiles/{id}** — Permanently delete. Response: 204.++**PATCH /profiles/{id}** — Update name. Body: `{ name?: string }`++---++## Skills++**POST /skills** — Create a skill (turn a website into an API endpoint).+Body: `{ goal: string, agent_prompt: string, ... }`+Response: SkillView.++**GET /skills** — List all skills.++**GET /skills/{id}** — Get skill details.++**POST /skills/{id}/execute** — Execute a skill.+Body: `{ parameters: {} }`++**POST /skills/{id}/refine** — Refine with feedback (free).+Body: `{ feedback: string }`++**POST /skills/{id}/cancel** — Cancel skill training.++**POST /skills/{id}/rollback** — Rollback to previous version.++**GET /skills/{id}/executions** — List skill executions.++**GET /skills/{id}/executions/{eid}/output** — Get execution output.++---++## Marketplace++**GET /marketplace/skills** — Browse community skills.++**GET /marketplace/skills/{slug}** — Get marketplace skill details.++**POST /marketplace/skills/{id}/clone** — Clone skill to your workspace.++**POST /marketplace/skills/{id}/execute** — Execute a marketplace skill.+Body: `{ parameters: {} }`++---++## Billing++**GET /billing/account** — Account info and credits.+Response: `{ name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo: { planName, subscriptionStatus?, subscriptionId?, subscriptionCurrentPeriodEnd?, subscriptionCanceledAt? }, projectId }`++---++## Pagination++All list endpoints use page-based pagination:++| Param | Type | Description |+|-------|------|-------------|+| pageSize | integer | Items per page |+| pageNumber | integer | Page number (1-based) |++Response includes: `{ items: [...], totalItems, pageNumber, pageSize }`++---++## Enums++| Enum | Values |+|------|--------|+| TaskStatus | `started`, `paused`, `finished`, `stopped` |+| TaskUpdateAction | `stop`, `pause`, `resume`, `stop_task_and_session` |+| SessionStatus | `active`, `stopped` |+| BrowserSessionStatus | `active`, `stopped` |+| ProxyCountryCode | `us`, `uk`, `fr`, `it`, `jp`, `au`, `de`, `fi`, `ca`, `in` (+185 more) |+| SupportedLLMs | `browser-use-llm`, `gpt-4.1`, `gpt-4.1-mini`, `o4-mini`, `o3`, `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-flash-latest`, `gemini-flash-lite-latest`, `claude-sonnet-4-20250514`, `gpt-4o`, `gpt-4o-mini`, `llama-4-maverick-17b-128e-instruct`, `claude-3-7-sonnet-20250219` |+| UploadContentType | `image/jpg`, `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`, `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/plain`, `text/csv`, `text/markdown` |++## Response Schemas++**TaskItemView:** id, sessionId, llm, task, status, startedAt, finishedAt?, metadata?, output?, browserUseVersion?, isSuccess?++**TaskView:** extends TaskItemView + steps: TaskStepView[], outputFiles: FileView[]++**TaskStepView:** number, memory, evaluationPreviousGoal, nextGoal, url, screenshotUrl?, actions: string[]++**FileView:** id, fileName++**SessionItemView:** id, status, liveUrl?, startedAt, finishedAt?++**SessionView:** extends SessionItemView + tasks: TaskItemView[], publicShareUrl?++**BrowserSessionItemView:** id, status, liveUrl?, cdpUrl?, timeoutAt, startedAt, finishedAt?++**ProfileView:** id, name?, lastUsedAt?, createdAt, updatedAt, cookieDomains?: string[]++**ShareView:** shareToken, shareUrl, viewCount, lastViewedAt?++**AccountView:** name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo, projectIddiff --git a/skills/browser-use-docs/references/cloud/api-v3.md b/skills/browser-use-docs/references/cloud/api-v3.mdnew file mode 100644index 000000000..f1f6ef075--- /dev/null+++ b/skills/browser-use-docs/references/cloud/api-v3.md@@ -0,0 +1,257 @@+# BU Agent API (v3 — Experimental)++Next-generation agent API. Session-based, token-based billing, workspaces, message history.++## Table of Contents+- [Authentication](#authentication)+- [SDK Setup](#sdk-setup)+- [run() — Execute a Task](#run--execute-a-task)+- [REST Endpoints](#rest-endpoints)+- [Sessions](#sessions)+- [Messages](#messages)+- [Files](#files)+- [Workspaces](#workspaces)+- [Polling & Terminal Statuses](#polling--terminal-statuses)+- [Error Handling](#error-handling)+- [Session Statuses & Enums](#session-statuses--enums)+- [Response Schemas](#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+# 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+// 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++```python+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++| Param | Type | Description |+|-------|------|-------------|+| task | string | **Required.** What to do. |+| model | string | `"bu-mini"` (default, faster/cheaper) or `"bu-max"` (more capable) |+| output_schema | Pydantic/Zod | Structured output schema |+| session_id | string | Reuse existing session |+| keep_alive | boolean | Keep session idle after task (default: false) |+| max_cost_usd | float | Cost cap in USD; agent stops if exceeded |+| profile_id | string | Browser profile UUID |+| proxy_country_code | string | Residential proxy country (195+ countries) |+| workspace_id | string | Attach workspace for file I/O |++### Structured Output++```python+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++| Field | Type | Description |+|-------|------|-------------|+| output | str / BaseModel | Task result (typed if schema provided) |+| id | uuid | Session ID |+| status | string | Session status |+| model | string | bu-mini or bu-max |+| title | string? | Auto-generated title |+| live_url | string | Real-time browser monitoring URL |+| profile_id | string? | Echo of request |+| proxy_country_code | string? | Echo of request |+| max_cost_usd | float? | Echo of request |+| total_input_tokens | int | Input tokens used |+| total_output_tokens | int | Output tokens used |+| llm_cost_usd | string | LLM cost |+| proxy_cost_usd | string | Proxy cost |+| proxy_used_mb | string | Proxy data used |+| total_cost_usd | string | Total cost |+| created_at | datetime | Session creation time |+| updated_at | datetime | Last update time |++---++## 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.++| Param | Type | Description |+|-------|------|-------------|+| limit | int | Max messages per page (default 50, max 100) |+| after | string | Cursor for forward pagination |+| before | string | Cursor for backward pagination |++Response: `{ messages: [{ id, role: "user"|"assistant", data: string, timestamp }], next_cursor?, has_more: boolean }`++### Files++**GET /sessions/{id}/files** — List files in session workspace.++| Param | Type | Description |+|-------|------|-------------|+| include_urls | boolean | Include presigned download URLs (60s expiry) |+| prefix | string | Filter by path prefix (e.g. `"outputs/"`) |+| limit | int | Max per page (default 50, max 100) |+| cursor | string | Pagination cursor |++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++| Strategy | Behavior |+|----------|----------|+| `"session"` (default) | Destroy sandbox completely |+| `"task"` | Stop current task, keep session alive for follow-ups |++```python+await client.sessions.stop(session_id, strategy="task") # keep session+await client.sessions.stop(session_id, strategy="session") # destroy+```++---++## Error Handling++```python+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++| Status | Description |+|--------|-------------|+| `created` | Session created, not yet running |+| `idle` | Task completed, session still alive (keep_alive=True) |+| `running` | Task in progress |+| `stopped` | Manually stopped |+| `timed_out` | Session timed out |+| `error` | Session errored |++**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 60sdiff --git a/skills/browser-use-docs/references/cloud/api.md b/skills/browser-use-docs/references/cloud/api.mddeleted file mode 100644index a071f1a4d..000000000--- a/skills/browser-use-docs/references/cloud/api.md+++ /dev/null@@ -1,228 +0,0 @@-# Cloud API Reference (v2 + v3)--## Table of Contents-- [Authentication](#authentication)-- [Core Concepts](#core-concepts)-- [SDK Methods](#sdk-methods)-- [REST Endpoints (v2)](#rest-endpoints-v2)-- [V3 API](#v3-api)-- [Enums](#enums)-- [Response Schemas](#response-schemas)-------## Authentication--- **Header:** `X-Browser-Use-API-Key: <key>`-- **Base URL:** `https://api.browser-use.com/api/v2/`-- **Get key:** https://cloud.browser-use.com/new-api-key--## Core Concepts--- **Session** — Infrastructure container (one Browser, sequential Agents). Max 15 min (free) or 4 hours (paid).-- **Browser** — Chromium fork, CDP-controllable, stealth-optimized, adblockers built-in.-- **Agent** — LLM-powered framework for iterative browser steps. Independent judge verifies completion.-- **Model** — Best: `browser-use-llm` (ChatBrowserUse) — fastest, cheapest, routes to best frontier model.-- **Browser Profile** — Persistent cookies/localStorage/passwords across sessions. Uploadable from local Chrome.-- **Task** — Prompt (text + optional files/images) given to Agent.-- **Workspace** — Persistent file storage across sessions (v3).-- **Profile Sync** — `export BROWSER_USE_API_KEY=<key> && curl -fsSL https://browser-use.com/profile.sh | sh`--## SDK Methods--### Python--```python-from browser_use_sdk import BrowserUse-client = BrowserUse() # BROWSER_USE_API_KEY env var--# Tasks-result = await client.run("task", llm="browser-use-llm", output_schema=MyModel)-task = await client.tasks.get(task_id)--# Sessions-session = await client.sessions.create(profile_id="uuid", proxy_country_code="us")-session = await client.sessions.get(session_id)-await client.sessions.stop(session_id)-share = await client.sessions.create_share(session_id)--# Browsers-browser = await client.browsers.create(profile_id="uuid", proxy_country_code="us", timeout=60)-await client.browsers.stop(session_id)--# Profiles-profiles = await client.profiles.list()-profile = await client.profiles.create(name="my-profile")-await client.profiles.update(profile_id, name="new-name")-await client.profiles.delete(profile_id)--# Files-url = await client.files.session_url(session_id, file_name="doc.pdf", content_type="application/pdf", size_bytes=1024)-output = await client.files.task_output(task_id, file_id)--# Billing-account = await client.billing.account()--# Skills-skill = await client.skills.create(...)-result = await client.skills.execute(skill_id, params={})-await client.skills.refine(skill_id, feedback="...")-skills = await client.marketplace.list()-```-------## REST Endpoints (v2)--### Billing--**GET /billing/account** — Account info and credit balances.-Response: `{ name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo, projectId }`--### Tasks--**GET /tasks** — Paginated list.-Params: `pageSize`, `pageNumber`, `sessionId?`, `filterBy?` (TaskStatus), `after?`, `before?`--**POST /tasks** — Create task. Auto-creates session or uses existing.--| Param | Type | Required | Description |-|-------|------|----------|-------------|-| task | string | **yes** | Task prompt |-| llm | SupportedLLMs | no | Model (default: browser-use-llm) |-| startUrl | string | no | Initial URL |-| maxSteps | integer | no | Max agent steps |-| structuredOutput | string | no | JSON schema |-| sessionId | uuid | no | Existing session |-| metadata | object | no | Key-value metadata |-| secrets | object | no | Sensitive key-value data |-| allowedDomains | string[] | no | Domain restrictions |-| opVaultId | string | no | 1Password vault ID |-| highlightElements | boolean | no | Highlight elements |-| flashMode | boolean | no | Fast mode |-| thinking | boolean | no | Enable thinking |-| vision | boolean\|"auto" | no | Vision mode |-| systemPromptExtension | string | no | Extend system prompt |--Response (202): `{ id, sessionId }`-Errors: 400 (busy), 404 (not found), 422 (validation), 429 (rate limit)--**GET /tasks/{task_id}** — Detailed info with steps and output files.--**PATCH /tasks/{task_id}** — Control: `{ action: "stop"|"pause"|"resume"|"stop_task_and_session" }`--**GET /tasks/{task_id}/logs** — Download URL: `{ downloadUrl }`--### Sessions--**GET /sessions** — Paginated list. Params: `pageSize`, `pageNumber`, `filterBy?`--**POST /sessions** — Create. Body: `{ profileId?, proxyCountryCode?, startUrl? }`-Response (201): SessionItemView. Errors: 404, 429.--**GET /sessions/{id}** — Detailed info with tasks.--**PATCH /sessions/{id}** — Stop: `{ action: "stop" }`--**GET /sessions/{id}/public-share** — Share info.--**POST /sessions/{id}/public-share** — Create share (201).--**DELETE /sessions/{id}/public-share** — Remove share (204).--### Browsers--**GET /browsers** — Paginated list.--**POST /browsers** — Create. Body: `{ profileId?, proxyCountryCode?, timeout? }`-Pricing: $0.05/hr upfront, refund on stop, min 1 min. Free: 15 min max, Paid: 4 hrs.-Response (201): BrowserSessionItemView (has `cdpUrl`, `liveUrl`). Errors: 403, 404, 429.--**GET /browsers/{id}** — Detailed info.--**PATCH /browsers/{id}** — Stop: `{ action: "stop" }` (unused time refunded).--### Files--**POST /files/sessions/{id}/presigned-url** — Upload URL.-Body: `{ fileName, contentType, sizeBytes }`. Response: `{ url, method:"POST", fields, fileName, expiresIn }`--**POST /files/browsers/{id}/presigned-url** — Same for browser sessions.--**GET /files/tasks/{task_id}/output-files/{file_id}** — Download URL: `{ id, fileName, downloadUrl }`--### Profiles--**GET /profiles** — Paginated list.--**POST /profiles** — Create: `{ name? }`. Error: 402 (subscription needed).--**GET /profiles/{id}** — Details.--**DELETE /profiles/{id}** — Delete (204).--**PATCH /profiles/{id}** — Update: `{ name? }`-------## V3 API--Experimental next-gen agent. Token-based billing, workspaces, session messages.--```python-from browser_use_sdk.v3 import AsyncBrowserUse--client = AsyncBrowserUse()--# Run task-result = await client.run("Find top HN post")--# Sessions with messages-session = await client.sessions.create(task="...", keep_alive=True)-messages = await client.sessions.messages(session.id)--# Workspaces (persistent files)-workspace = await client.workspaces.create(name="my-workspace")-await client.sessions.upload_files(session.id, workspace_id=workspace.id, files=[...])-files = await client.sessions.files(session.id)--# Cleanup-await client.sessions.stop(session.id)-await client.close()-```-------## Enums--| Enum | Values |-|------|--------|-| TaskStatus | started, paused, finished, stopped |-| TaskUpdateAction | stop, pause, resume, stop_task_and_session |-| SessionStatus | active, stopped |-| BrowserSessionStatus | active, stopped |-| ProxyCountryCode | us, uk, fr, it, jp, au, de, fi, ca, in (+185 more) |-| SupportedLLMs | browser-use-llm, gpt-4.1, gpt-4.1-mini, o4-mini, o3, gemini-2.5-flash, gemini-2.5-pro, gemini-flash-latest, gemini-flash-lite-latest, claude-sonnet-4-20250514, gpt-4o, gpt-4o-mini, llama-4-maverick-17b-128e-instruct, claude-3-7-sonnet-20250219 |-| UploadContentType | image/jpg, jpeg, png, gif, webp, svg+xml, application/pdf, msword, vnd.openxmlformats*.document, vnd.ms-excel, vnd.openxmlformats*.sheet, text/plain, csv, markdown |--## Response Schemas--**TaskItemView:** id, sessionId, llm, task, status, startedAt, finishedAt?, metadata?, output?, browserUseVersion?, isSuccess?--**TaskView:** extends TaskItemView + steps: TaskStepView[], outputFiles: FileView[]--**TaskStepView:** number, memory, evaluationPreviousGoal, nextGoal, url, screenshotUrl?, actions[]--**FileView:** id, fileName--**SessionItemView:** id, status, liveUrl?, startedAt, finishedAt?--**SessionView:** extends SessionItemView + tasks: TaskItemView[], publicShareUrl?--**BrowserSessionItemView:** id, status, liveUrl?, cdpUrl?, timeoutAt, startedAt, finishedAt?--**ProfileView:** id, name?, lastUsedAt?, createdAt, updatedAt, cookieDomains?[]--**ShareView:** shareToken, shareUrl, viewCount, lastViewedAt?--**AccountView:** name?, monthlyCreditsBalanceUsd, additionalCreditsBalanceUsd, totalCreditsBalanceUsd, rateLimit, planInfo, projectIddiff --git a/skills/browser-use-docs/references/cloud/browser-api.md b/skills/browser-use-docs/references/cloud/browser-api.mdindex 755539ab1..063aff66d 100644--- a/skills/browser-use-docs/references/cloud/browser-api.md+++ b/skills/browser-use-docs/references/cloud/browser-api.md@@ -13,10 +13,15 @@ Connect directly to Browser Use stealth browsers via Chrome DevTools Protocol.## WebSocket Connection-Single URL with all config as query params. Browser auto-stops on disconnect.+Single URL with all config as query params. Browser **auto-starts on connect** and **auto-stops on disconnect** — no REST calls needed to start or stop.```-wss://connect.browser-use.com/?apiKey=YOUR_KEY&proxyCountryCode=us&timeout=30+wss://connect.browser-use.com?apiKey=YOUR_KEY&proxyCountryCode=us&timeout=30+```++CDP discovery is also available over HTTPS (for tools that use HTTP auto-discovery):+```+https://connect.browser-use.com/json/version?apiKey=YOUR_API_KEY```### Query Parameters