Human Browser

Human Browser — a cloud browser agent. Send a goal in plain English; a real Chromium on a residential IP in your chosen country (75 available) does the job — logs in, clicks, fills forms, solves CAPTCHAs, reads pages — and returns the answer plus a live viewer URL a human can watch and take over. Logins persist per profile, so the second run on a site skips the login. USE IT FOR: tasks a plain HTTP fetch cannot do — logged-in dashboards, sites behind Cloudflare/Turnstile/DataDome/PerimeterX, geo-restricted pages, multi-step forms, uploads. DO NOT use it for public APIs or static pages a fetch can read (cheaper, faster). Legitimate, user-authorized tasks only. TOKEN: Authorization: Bearer hb_live_... on every call (never in a URL). Get one at https://humanbrowser.cloud/account (Google or email sign-in). No free credit; the first top-up can be $1 (card), later top-ups from $5. Prepaid balance, no subscription, never expires. PRICE (list v2, since 2026-10-01; machine-readable https://humanbrowser.cloud/api/plans): $0.02 per agent step with the LLM included, $0.10 per browser-HOUR billed per second (sessions under 30 s and human-takeover time free), $0.005 per solved CAPTCHA, $4/GB residential traffic. Median successful task $0.24 (p25 $0.12, p75 $0.39), about 8 steps — $1 is roughly 4 tasks. RUN A TASK (A2A JSON-RPC 2.0, POST https://agent.humanbrowser.cloud/a2a): {"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"role":"user","messageId":"m1","parts":[{"kind":"text","text":"Open https://news.ycombinator.com and return the top 3 story titles as JSON."}]}}} 1. message/send answers in seconds, once the browser is up: a Task {id:"t_…", status.state:"working", metadata.viewerUrl, metadata.sessionId, metadata.profile}. The run continues detached. Show metadata.viewerUrl to your user. 2. Poll tasks/get {"id":"t_…"} every 3-5 s (no long-poll). working = still running, not a failure; status.message is a progress line ("Step 12/100 on example.com — …") you may quote verbatim. Or use message/stream (SSE), or set metadata.callback_url (https) to receive the final Task by POST. 3. Terminal states: completed | failed | canceled | input-required. The answer is metadata.outcome.result (also artifacts[0]); metadata.recordUrl replays the run. Files the run downloaded come back as kind:file parts and metadata.outcome.produced_files. 4. Finished tasks stay readable for 30 minutes, then tasks/get returns -32001 Task not found — save what you need. Typical duration: 20-90 s on a warm profile, 3-8 min for a first login on a hostile site. Hard limits: 2 h and 100 steps per task. CREDENTIALS — never in the goal text. Add a DataPart with FLAT string values and refer to each key as <key> in the goal: {"kind":"data","metadata":{"sensitive":true},"data":{"email":"[email protected]","password":"…"}} + text "Log into example.com as <email> with <password>, then …" The value is typed at action time and never reaches the model, logs or results. A secret written straight into the goal text IS seen by the model (and may be refused as -32602 credential-in-goal) — always use the DataPart. URLs are not substituted: write them plainly. Text that must be pasted exactly: <verbatim name="pitch">…</verbatim>. Inbox OTP fetch: add hb_otp_imap_user / hb_otp_imap_pass (/ hb_otp_imap_host, default imap.gmail.com) to the same DataPart. INPUT-REQUIRED (the agent needs an OTP, a magic link, a decision): state=input-required, final; metadata.input_required = {req_id, question, kind, sensitive, timeout_s, deadline}. While it is still paused, answer with message/send: message.referenceTaskIds=[taskId], message.metadata.in_reply_to=req_id, parts=[{kind:"text",text:"<answer>"}] (or {kind:"data",data:{decline:true,reason}}); message.taskId=<taskId> or re-sending on the same contextId also works. The pause message carries a ready resume_example. A human can answer in the viewer instead. No answer by the deadline = auto-decline. If the task is already terminal, do not resume — start a NEW task whose goal carries the full context and the answer. FILES IN: attach {"kind":"file","file":{"name":"a.jpg","mimeType":"image/jpeg","uri":"https://…"}} (uri = public http(s) URL, up to 25 MB; or base64 "bytes" — the whole JSON-RPC request must stay under 8 MB; max 8 files) and say in the goal what to upload where. OPTIONAL metadata (params.metadata or message.metadata): country (iso2, e.g. us, gb, de, jp — see actions/list_countries), profile (slug; default = first domain in the goal, e.g. adsy.com -> adsy; set it for multiple identities on one site), force_new (fresh isolated browser), mobile_ua (iPhone Safari), callback_url, overrides {submit_max 1-10, allow_resubmit}. Engine, model, mode, proxy and CAPTCHA handling are chosen by the server — leave them unset unless you measured a reason. SESSIONS: tasks on the same profile reuse the same live browser (still logged in) and queue behind each other (up to 20 waiting); different profiles run in parallel. Up to 10 concurrent sessions per token. ERRORS: HTTP 401 / -32001 Unauthorized (bad token) · HTTP 402 / -32001 Payment Required {reason:"balance-depleted", topup_url} · -32602 Invalid params with detail "goal_rejected (<reason>): …" or "credential-in-goal (…)" (empty, junk, unfilled ${template}, or program code instead of an instruction — rewrite the goal; nothing billed) · task failed with metadata.error.code="circuit_open" (this token failed 3x in 24 h on that host for the same non-retryable reason, e.g. locked account or wrong password; fix the cause — it resets on a success or after 24 h; nothing billed) · metadata.error.code="session-cap" / "capacity" / "proxy_unavailable" (retry later) · -32601 Method not found (custom actions need the actions/ prefix) · -32002 Task not in input-required state. On failed, read metadata.outcome.result, metadata.outcome.blocks ({code, retryable, how_to_retry}) and metadata.postmortem (about 30 s later) before retrying; blocks with retryable:false mean verify first — a blind retry may submit twice. Report only what these fields say; do not guess "blocked by a CAPTCHA". ACTIONS (same endpoint, method "actions/<name>"): list_countries, list_models, list_engines, switch_proxy_country, get_cost_snapshot, get_page_diagnostics (why a page looks broken: ok | degraded | page_did_not_start | broken_by_us), get_screenshots (frame links, not bytes), list_learned_apis + call_site_api (use a site's own API from your session), upload_file, set_profile_name, discover_endpoints. See customActions. MCP: the same agent at https://agent.humanbrowser.cloud/mcp (Streamable HTTP, Bearer token or OAuth 2.1) with tools humanbrowser_run, humanbrowser_status, humanbrowser_viewer_url. Full reference: https://humanbrowser.cloud/llms-full.txt

Skills

• Browser Task
  Free-form web task in plain language: navigate, search, click, fill forms, read and extract. Returns the answer as text (metadata.outcome.result, artifacts[0]) plus a live viewer URL (metadata.viewerUrl) the end user can watch or take over.
  browserautomationscrapingnavigationstealth
• Login and Scrape
  Log into a site with credentials supplied in a sensitive DataPart, then extract data from the logged-in pages. DataPart: {"kind":"data","metadata":{"sensitive":true},"data":{"email":"...","password":"..."}} (flat strings); goal refers to <email> and <password>. Values are typed at action time and never echoed. Cookies persist on the profile, so later tasks on the same site skip the login. If the site asks for a code the agent pauses with input-required; add hb_otp_imap_user / hb_otp_imap_pass to the DataPart and it reads the code from the inbox itself.
  browserloginscrapingauthenticated
• Meta Business Workflow
  Drive Meta Business Suite / Facebook Ads Manager / Meta-owned web properties on behalf of a specific Meta account, using customer-supplied cookies+proxy+UA bundled into a persistent AdsPower-backed Chromium profile. Use this when the goal requires touching an authenticated Meta surface (pulling campaign performance, dispatching ad creation, reading Page inbox, exporting audience reports) and the end-user has a Meta account they already operate manually. Pass metadata.engine='adspower' and metadata.profile=<account_slug> on message/send, plus the account bundle (cookies, user agent, proxy) in a DataPart with metadata.sensitive=true so the same fingerprint is reused across follow-up tasks. Surcharge: +$0.05/session. Login flows on Meta routinely trip 2FA / checkpoint / device-trust prompts, so relaying the response viewer URL to the end user is typically helpful. Since 2026-09-07: Meta's div[role=button] controls that ignored synthetic clicks (Create a business portfolio, Save changes, Post, I accept) are clicked with a real OS mouse automatically when the first click changes nothing; avatar/cover uploads take an attached FilePart or a public URL; cover repositioning uses a real drag. A named profile (metadata.profile) keeps the Facebook login between tasks — do not pass force_new for follow-up work on the same account.
  browsermetafacebookads-managerbusiness-suitemulti-accountadspower
• Fill Form
  Open a URL, fill a form from structured data, submit, and report the confirmation. Put non-secret field values in a plain DataPart (they become context for the agent) and secrets in a sensitive one. A submit guard stops repeated clicks on submit/pay buttons; if metadata.outcome.blocks shows submit_guard (retryable:false), check whether the submission landed before re-running with metadata.overrides.
  browserformsubmit
• Scrape URL
  URL in, structured data out: "Extract name, price and availability from <url> as JSON". The page is rendered in real Chromium (JavaScript, cookies, residential IP), so it works on SPAs, logged-in pages and geo-restricted views. The JSON comes back as text in metadata.outcome.result. For bulk static pages a plain HTTP scraper is cheaper.
  browserscrapingurl-to-jsonstructured-extraction
• Relay (reverse-API)
  Experimental: for a few mapped domains (property portals, hotel aggregators), metadata.engine="relay" calls the site's own JSON endpoints instead of driving a browser — faster and cheaper. There is no public catalog of mapped domains; if a domain is not mapped the task fails fast and should be re-run without engine.
  reverse-apirelayfast-pathno-browsercost-optimized
• Hostile Site Solver
  Sites behind interactive anti-bot walls (Cloudflare Managed Challenge / Turnstile, DataDome, PerimeterX press-and-hold, Akamai). Leave engine unset — the router picks the path that works for that vendor (stealth Chromium, remote browser or OS-level computer-use driving). CAPTCHA solves are $0.005 each, only when one is solved. If a page still looks broken, call actions/get_page_diagnostics before concluding the site blocked you.
  anti-botcloudflareturnstileperimeterxdatadomecuahard-target
• Email-Verified Signup
  Sign up on sites that need Turnstile + email verification. Sensitive DataPart (flat strings): {"email":"...","password":"...","hb_otp_imap_user":"...","hb_otp_imap_pass":"...","hb_otp_imap_host":"imap.gmail.com"} — the agent registers, solves the challenge, reads the verification code or magic link from that inbox over IMAP, completes verification and returns what you asked for (API key, dashboard URL). Use a mailbox you control; use an app password for Gmail.
  signuponboardingemail-otpturnstilehunterapollozerobounce
• Network endpoint discovery
  Capture a page's own XHR/fetch traffic from a live session and return a de-duplicated list of its API endpoints with freshness signals. No LLM, no per-step charge; cookie/authorization headers are stripped. Call actions/discover_endpoints {taskId (or sessionId+sessionKey), url, country?, duration_ms<=90000, scroll?, reload?, match_url?, freshness_fields?} on a session you already started, then poll actions/get_discovery_result {job_id}.
  browsernetworkreverse-apidiscoveryapi-scout

How to call

https://agent.humanbrowser.cloud/a2a

Listed in

Directories this entry was found in.