Browser Rendering is an evidence adapter, not a better fetch()

Evidence status

Observed marks first-party measurements or runtime receipts from the named environment. Derived marks arithmetic calculated from cited inputs. Specified marks vendor or standards documentation. Implemented and deployed name code and live-state evidence, respectively. Reproduced means the stated procedure was rerun. Externally attested marks operator reports; those reports show that an experience occurred, not that it is universal.

The endpoint is a choice about evidence

Cloudflare exposes ten Quick Actions in the current documentation, including the beta crawl action. They overlap at the input—usually a URL—but not at the output. Choosing by convenience rather than by evidence type is how a screenshot gets mistaken for data, a Markdown conversion gets mistaken for the DOM, or a link inventory gets reconstructed expensively from a general browser session.

/snapshot is especially useful for evidence work because one browser state can yield a visual surface and structural surfaces together. Cloudflare says the action defaults to HTML plus screenshot and can add Markdown and the accessibility tree. That is not just fewer requests. It reduces the chance that two captures were made from different page states. The receipt should still record each format separately and hash the bytes separately, because a screenshot and HTML prove different things.

The inverse rule matters too. If a stable endpoint already returns JSON, call it with ordinary HTTP. If static HTML contains the needed text, use ordinary HTTP. If all that is required is a status code or header, a browser weakens the measurement by adding navigation, rendering and conversion work that the question never asked for.

A browser can execute a page without proving the page is complete

JavaScript execution is necessary for many modern pages, but it is not a completion oracle. Single-page applications often paint an initial shell, issue more requests, then reveal content after a selector appears. Cloudflare's Quick Action documentation repeatedly warns that the default result may be incomplete for SPAs and points to waitForSelector or navigation wait options.

That means every browser capability needs an explicit completion contract. “Open this URL” is not one.

A useful row therefore separates navigation from success:

{
  "key": "BROWSER_MARKDOWN",
  "what": "Return Markdown after the named page state exists.",
  "args": {
    "url": "https URL",
    "wait_for_selector": "optional CSS selector",
    "timeout_ms": "bounded integer"
  },
  "authority": {
    "hosts": ["developers.cloudflare.com"],
    "cookies": false,
    "custom_headers": []
  },
  "receipt": {
    "final_url": true,
    "status": true,
    "browser_ms": true,
    "body_sha256": true,
    "selector_observed": true
  }
}

The row is discoverable because its what names Markdown and page state. It is invokable because the arguments are concrete. It is auditable because the allowed hosts and credential channels are visible. It is replayable because the receipt records the final URL, completion observation and content hash. The same row can project to REST documentation, a model tool schema, a CLI command and an admin form without inventing four contracts.

The first-party receipt: 208 browser milliseconds, not a speed claim

On 26 July 2026 this build called the production /browser-rendering/markdown REST action against https://example.com. The token was read from the local credential store and was never copied into the artifact. The response was successful and contained the expected “Example Domain” heading.

This is a receipt for one request from one client to one stable target. It is not a latency benchmark, an availability claim, or evidence that arbitrary protected sites will render. Client elapsed time includes network and API overhead. The browser-time header measures billable browser work for that Quick Action, not total wall time.

The reproduction is deliberately small:

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-rendering/markdown" \
  -H "Authorization: Bearer $BROWSER_RENDERING_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com"}'

The portable version should read the account identifier and token from environment or a secret store, never from a catalogue row, prompt, receipt or shell history. Record the response status, final representation hash and X-Browser-Ms-Used; discard the bearer token before ledgering.

The bill is browser time, and sessions add a second meter

Cloudflare distinguishes Quick Actions from Browser Sessions. Quick Actions are charged for browser hours. Direct sessions through Puppeteer, Playwright or CDP are charged for browser hours and, on paid plans above the included allowance, concurrent browsers.

The current published table gives Workers Free ten browser minutes per day. Workers Paid includes ten browser hours per month and then charges $0.09 for each additional browser hour. Browser Sessions include three concurrent browsers on Free; Paid includes ten averaged monthly and then lists $2 for each additional concurrent browser. The Quick Action response header reports browser milliseconds used, which is the useful per-invocation receipt field.

The 120-browser paid limit and the ten-browser paid price inclusion answer different questions. Conflating them makes a cost table wrong. So does multiplying the 208 ms receipt by the $0.09 rate and presenting the fraction of a cent as an invoice: Cloudflare aggregates daily seconds and rounds the monthly browser-hour total. The individual header supports attribution and anomaly detection; billing still follows the aggregate rules.

Direct sessions need stricter lifecycle code:

let browser;
try {
  browser = await puppeteer.launch(env.BROWSER);
  const page = await browser.newPage();
  await page.goto(target, { waitUntil: "networkidle0" });
  return await page.content();
} finally {
  if (browser) await browser.close();
}

Cloudflare warns that a session left open continues consuming browser time until the inactivity timeout. An issue in cloudflare/workers-sdk also reported browser.close() hanging under local Vite and Wrangler development while production worked. That report is one historical local-development reproduction, not evidence that current production close calls hang. It is enough to justify a bounded close operation, a recorded close reason and a test of local and deployed paths separately.

“Cloud browser” does not mean “bypass”

Changing the User-Agent does not turn Browser Run into an unidentifiable residential client. Cloudflare states that Browser Run requests are always identified as bot traffic and that a custom User-Agent does not bypass bot protection. A remote Chrome may execute client JavaScript that plain fetch cannot, yet the destination can still challenge or refuse it.

This has two consequences.

First, the browser capability must report refusal as refusal. A rendered challenge page with status 200 is not the requested article. Success needs a content assertion: selector observed, expected heading present, schema satisfied, or another target-specific check.

Second, the system must not market Browser Run as a way around a publisher's controls. Robots rules, authorization, terms, rate limits and data handling remain part of the invocation policy. Browser execution changes the client. It does not confer permission.

One Hacker News commenter said they moved to remote browser rendering because bot protection made direct fetching unworkable. Another asserted that Perplexity was using Cloudflare Browser Rendering for scraping. Those are observations from named operators, not universal proof of bypass, permission, scale, reliability or present product behavior. They establish that practitioners reach for this category of tool in the exact gap between plain HTTP and executed pages. They do not settle whether any particular target should be fetched.

The output can be wrong even when the browser worked

Transport success and representation correctness are separate gates. A GitHub report against /crawl showed root-relative image paths being resolved as page-relative paths in converted Markdown, producing broken image URLs while the HTML output remained correct. That is an externally reported converter defect on particular pages, not proof that all current Markdown is broken. It demonstrates why the receipt should retain the source URL, format, converter version when available, and a second representation for material captures.

For critical evidence:

1. capture rendered HTML plus the representation used downstream;
2. retain the final URL after redirects;
3. hash both outputs;
4. validate required links or fields against the HTML;
5. label model-extracted JSON as derived;
6. store a screenshot when the claim is visual;
7. fail closed when a required selector or assertion is absent.

The /json action deserves an extra warning. Cloudflare documents it as AI-assisted extraction and says the default model is Workers AI's Llama 3.3 70B FP8 Fast unless another provider is supplied. A schema can constrain shape. It cannot make the content deterministic or true. JSON produced by a model is derived evidence and should preserve the prompt, schema, model identity, input hash and validation result. It should never overwrite the rendered source.

Crawl is a queue, not a big page request

The beta /crawl action is asynchronous. A POST creates a job; subsequent reads retrieve status and results. Cloudflare says jobs may run for up to seven days and results remain available for fourteen days. That temporal shape belongs in the catalogue contract. A row that blocks a model turn until an entire crawl completes is the wrong projection.

Use three capabilities instead:

CRAWL_CREATE(url, limit, depth, formats) -> job_id receipt
CRAWL_STATUS(job_id)                     -> progress receipt
CRAWL_RESULTS(job_id, cursor)            -> bounded page of artifacts

The catalogue can project those rows into an asynchronous REST API, terminal commands and model tools while retaining one authority policy and one lineage chain. Each result page should point back to the create receipt and catalogue snapshot.

Cloudflare's current Free limits specify five crawl jobs per day and one hundred pages per crawl. A March 2026 Hacker News comment multiplied those two numbers and questioned a 500-page daily ceiling. That is a reasonable reading of the Free limits now published, but the commenter described the documentation they saw and framed the concern more broadly. It is not independent evidence of a paid-plan cap. The current limits page says paid defaults can be increased and does not list the same crawl-specific table under Paid. The article therefore narrows the anecdote instead of repeating it as a current universal limit.

A second operator built a two-script, zero-dependency CLI covering all nine REST endpoints then documented, including /crawl. That externally attests that the REST surface was usable as a coherent toolset for one builder. It does not prove our adapter, our credentials or today's endpoint. Our own proof remains the measured /markdown receipt above.

The authority boundary is larger than the URL

A browser can send cookies, custom headers, HTTP credentials and injected scripts. It can follow redirects to a different host, load subresources from many hosts, download data, and execute code supplied by the destination. Treating authority as an allowlist on the initial URL is inadequate.

The minimum policy envelope includes:

This is SSRF defense and denial-of-wallet defense in one place. The model should never receive a raw “browse any URL with these headers” primitive when a narrower row can express the job. A malicious directory row must not be able to expand its own host authority, supply a metadata address, or ask the adapter to return cookies in the receipt.

The receipt should be useful without becoming a credential leak:

{
  "capability_key": "BROWSER_MARKDOWN",
  "catalogue_version": "sha256:…",
  "requested_url": "https://example.com",
  "final_url": "https://example.com/",
  "authority_policy": "public-docs-v3",
  "completion": {"kind": "heading", "observed": true},
  "format": "markdown",
  "http_status": 200,
  "browser_ms_used": 207.706,
  "elapsed_ms": 1418,
  "body_sha256": "sha256:…",
  "credentials": {"token": "redacted", "cookies_sent": false}
}

Replay means invoke the same capability version with the same public inputs and policy, then compare receipts. It does not mean persist and resend an expired token. Repair means change the row or adapter under review—perhaps the selector, format, timeout or allowed host—then issue a new catalogue version and preserve the failed receipt. The ledger makes failure part of lineage instead of rewriting history.

REST for bounded transforms; Puppeteer for interaction

Quick Actions cover common one-shot representations with smaller contracts. Puppeteer or Playwright is appropriate when the task genuinely requires interaction across states: click, type, authenticate, paginate, reuse a session, inspect requests, or coordinate multiple pages.

The decision can be mechanized in the canonical catalogue. Discovery exposes the specific transform first. Authority hides session tools from callers that do not need credentials or interaction. Invocation validates URL and completion conditions. Receipts normalize REST and session results into the same lineage fields. Repair can replace an implementation without changing the capability's public meaning.

This is where the system claim becomes concrete. One catalogue row drives discovery text, input schema, authority, adapter selection, receipt shape, replay, repair documentation, model-tool projection, CLI help and admin controls. The browser is not a second architecture. It is one implementation family behind the catalogue.

What the operator reports change—and what they do not

The people-source set is deliberately mixed.

• A Cloudflare engineer reported browser.close() hanging in local Vite and Wrangler development while production succeeded. This supports testing local and deployed lifecycle separately.
• A user reported REST error codes 7003 and 7000 despite a token and account identifier they had verified. This supports returning Cloudflare's structured error body and the chosen endpoint in the receipt; it does not prove the present API is generally misconfigured.
• A crawl user reported malformed root-relative image URLs in Markdown while HTML stayed correct. This supports cross-format validation.
• A commenter questioned crawl throughput based on the published limit arithmetic. This supports showing the limit calculation and reading the current plan table, not a universal paid-plan conclusion.
• A CLI author reported exercising the full REST family. This supports the coherence of Quick Actions as a practical interface for that author.
• Two other commenters described using or observing Browser Rendering for scraping and Markdown distillation. These support the use case, not permission, bypass success, commercial scale or adoption.

Operator evidence is valuable here because it reveals failure modes absent from a happy-path reference: lifecycle hangs, auth-shaped errors, converter defects and throughput surprises. It remains externally attested evidence. The specification defines the contract; the fresh receipt establishes what this build reproduced; operator reports tell us which edges deserve tests.

The operating rule

Use Browser Run when the thing you need does not exist until a browser executes the page, or when the required artifact is browser-specific. Name the representation. Name the completion condition. Constrain the authority. Meter browser time. Preserve the source alongside every derived form.

Do not call it a bypass. Do not call model-shaped JSON fact. Do not call one successful render availability. Do not call a historical issue a current universal defect.

When those boundaries are encoded once in the capability catalogue, the same browser operation can be discovered by a model, invoked from a terminal, projected as an API, receipted in the ledger, replayed after a change and repaired without losing its history. That—not remote Chrome by itself—is what makes Browser Rendering part of an operating system.