{"openapi": "3.1.0", "info": {"title": "Browser Use Cloud API", "version": "3.0.0", "description": "AI browser automation agents in the cloud, payable per request with x402. POST a natural-language task and an agent navigates websites, fills forms, clicks buttons, extracts structured data, and completes multi-step workflows. Stealth-enabled remote browsers with CAPTCHA solving, residential proxies, live session view, and optional structured output.", "x-guidance": "Create a browser automation session with POST /api/v3/sessions (JSON body with a natural-language \"task\"), then poll GET /api/v3/sessions/{session_id} until status is \"stopped\" and read \"output\". Managing a session you created is free \u2014 polling it, reading its step-by-step message log (GET .../messages), stopping (POST .../stop), deleting (DELETE), and dispatching follow-up tasks to it (POST /api/v3/sessions with \"sessionId\" in the body) need no payment or auth; you only pay when opening a new browser. Payments are credit top-ups, not per-call fees: each payment adds whatever amount you authorize (min $0.01), and unused credits carry over. Recommended: a free account at https://cloud.browser-use.com \u2014 x402 payments with its API key in the X-Browser-Use-API-Key header credit that account. Actual usage is metered from credits: sessions ~$0.00017/min plus $0.002-$0.10 per agent step depending on the model; a typical task costs $0.05-$0.50. Full API reference: https://docs.browser-use.com", "contact": {"email": "support@browser-use.com"}}, "servers": [{"url": "https://x402.api-staging-ufcbwvyv9yifyyvc3.browser-use.com"}], "paths": {"/api/v3/sessions": {"post": {"operationId": "createSession", "summary": "Run a browser automation task with an AI agent", "description": "Payment is only required when opening a new browser. Passing \"sessionId\" dispatches a follow-up task to an existing session you created \u2014 free, no payment or auth needed.", "tags": ["Sessions"], "x-payment-info": {"price": {"mode": "dynamic", "currency": "USD", "min": "0.01", "max": "100.00"}, "protocols": [{"x402": {}}]}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"task": {"type": "string", "description": "Natural-language instructions for the agent to execute in a remote browser."}, "model": {"type": "string", "description": "LLM powering the agent: \"gemini-3-flash\" (fast/cheap), \"claude-sonnet-5\" (balanced), \"claude-opus-4.7\" (most capable, default), \"claude-opus-4.8\" (newest Opus tier)."}, "sessionId": {"type": "string", "description": "Dispatch the task to an existing idle session instead of creating a new one."}, "keepAlive": {"type": "boolean", "description": "Keep the session idle after the task completes so follow-up tasks reuse browser state."}, "maxCostUsd": {"type": "number", "description": "Maximum total cost in USD for this session; the task stops when reached."}, "proxyCountryCode": {"type": "string", "description": "Country code for the browser proxy (e.g. \"US\", \"DE\", \"JP\"). Defaults to \"US\"."}, "outputSchema": {"type": "object", "description": "JSON Schema the agent's final output must conform to; enables structured output."}, "enableRecording": {"type": "boolean", "description": "Record a video of the browser session, returned as recordingUrls."}}, "required": ["task"]}}}}, "responses": {"200": {"description": "Session created; poll it for progress and the final output.", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string", "description": "Session id \u2014 poll GET /api/v3/sessions/{session_id} for progress."}, "status": {"type": "string", "enum": ["created", "idle", "running", "stopped", "timed_out", "error"]}, "output": {"description": "Agent's final result: free-form text, or structured data when outputSchema was requested."}, "stepCount": {"type": "integer"}, "isTaskSuccessful": {"type": "boolean", "description": "Agent self-assessment of whether the task succeeded."}, "liveUrl": {"type": "string", "description": "Watch the browser session live."}, "recordingUrls": {"type": "array", "items": {"type": "string"}, "description": "Video recordings of the session when enableRecording was set."}}, "required": ["id", "status"]}}}}, "402": {"description": "Payment Required"}}}}, "/api/v3/sessions/{session_id}": {"get": {"operationId": "getSession", "security": [], "summary": "Poll a session for progress and the final output (free for sessions you created)", "tags": ["Sessions"], "parameters": [{"name": "session_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Session id returned by POST /api/v3/sessions."}], "responses": {"200": {"description": "Current session state and, once stopped, the final output.", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string", "description": "Session id \u2014 poll GET /api/v3/sessions/{session_id} for progress."}, "status": {"type": "string", "enum": ["created", "idle", "running", "stopped", "timed_out", "error"]}, "output": {"description": "Agent's final result: free-form text, or structured data when outputSchema was requested."}, "stepCount": {"type": "integer"}, "isTaskSuccessful": {"type": "boolean", "description": "Agent self-assessment of whether the task succeeded."}, "liveUrl": {"type": "string", "description": "Watch the browser session live."}, "recordingUrls": {"type": "array", "items": {"type": "string"}, "description": "Video recordings of the session when enableRecording was set."}}, "required": ["id", "status"]}}}}, "402": {"description": "Payment Required"}}}, "delete": {"operationId": "deleteSession", "security": [], "summary": "Delete a session (free for sessions you created)", "tags": ["Sessions"], "parameters": [{"name": "session_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Session id returned by POST /api/v3/sessions."}], "responses": {"204": {"description": "Session deleted."}, "402": {"description": "Payment Required"}}}}, "/api/v3/sessions/{session_id}/messages": {"get": {"operationId": "listSessionMessages", "security": [], "summary": "Read the agent's step-by-step message log (free for sessions you created)", "tags": ["Sessions"], "parameters": [{"name": "session_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Session id returned by POST /api/v3/sessions."}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100}, "description": "Maximum number of messages to return (default 10)."}, {"name": "after", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Cursor: return messages after this message id."}], "responses": {"200": {"description": "Agent messages in chronological order \u2014 the session's actions, observations, and decisions.", "content": {"application/json": {"schema": {"type": "object", "properties": {"messages": {"type": "array", "description": "The agent's message stream in chronological order.", "items": {"type": "object", "properties": {"id": {"type": "string"}, "role": {"type": "string", "description": "\"human\" for user-submitted tasks, \"ai\" for agent actions and responses."}, "type": {"type": "string", "description": "Message category, e.g. browser_action, planning, completion."}, "summary": {"type": "string", "description": "One-line human-readable description, e.g. \"Navigating to google.com\"."}, "data": {"type": "string", "description": "Raw message content: plain text, JSON, or structured action data."}, "screenshotUrl": {"type": "string", "description": "Browser screenshot at the time of this message (presigned, short-lived)."}, "createdAt": {"type": "string"}}}}, "hasMore": {"type": "boolean"}}, "required": ["messages", "hasMore"]}}}}, "402": {"description": "Payment Required"}}}}, "/api/v3/sessions/{session_id}/stop": {"post": {"operationId": "stopSession", "security": [], "summary": "Stop a session or its running task (free for sessions you created)", "tags": ["Sessions"], "parameters": [{"name": "session_id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Session id returned by POST /api/v3/sessions."}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"strategy": {"type": "string", "enum": ["session", "task"], "description": "\"session\" (default) destroys the sandbox entirely; \"task\" stops the running task but keeps the session alive for follow-ups."}}}}}}, "responses": {"200": {"description": "The stopped session.", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string", "description": "Session id \u2014 poll GET /api/v3/sessions/{session_id} for progress."}, "status": {"type": "string", "enum": ["created", "idle", "running", "stopped", "timed_out", "error"]}, "output": {"description": "Agent's final result: free-form text, or structured data when outputSchema was requested."}, "stepCount": {"type": "integer"}, "isTaskSuccessful": {"type": "boolean", "description": "Agent self-assessment of whether the task succeeded."}, "liveUrl": {"type": "string", "description": "Watch the browser session live."}, "recordingUrls": {"type": "array", "items": {"type": "string"}, "description": "Video recordings of the session when enableRecording was set."}}, "required": ["id", "status"]}}}}, "402": {"description": "Payment Required"}}}}}}