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

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