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

A measured Cloudflare Browser Run guide: choose evidence formats, define page completion, meter browser time, constrain authority, preserve source beside derived output, and receipt every invocation.

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

A plain HTTP client retrieves bytes. Cloudflare Browser Run can execute the page, wait for its state to settle, and return a representation chosen for the next operation: rendered HTML, Markdown, selected elements, links, a screenshot, a PDF, an accessibility tree, structured JSON, or an asynchronous crawl.

That distinction is the whole chapter. A browser belongs in this system only where the evidence depends on browser execution or a browser-specific representation. It should not become the default transport. Making it the default spends more time and money, enlarges the security boundary, and can still return a convincing but incomplete page.

The capability catalogue therefore does not contain one vague BROWSER tool. It contains explicit contracts: what representation is requested, what completion condition is required, what authority may leave the system, and what receipt must come back. The browser is the eyes. The canonical catalogue decides when those eyes may open and what counts as seeing.

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.

If the next operation needs	Quick Action	Returned evidence	Do not infer
Executed document markup	`/content`	rendered HTML	that every lazy region loaded
Human-readable text and links	`/markdown`	converted Markdown	pixel layout or exact DOM fidelity
Named fields from known selectors	`/scrape`	selector results	completeness outside those selectors
Link discovery	`/links`	extracted links	that every destination is safe or relevant
Visual state	`/screenshot`	raster image	semantic structure or hidden text
Printable artifact	`/pdf`	PDF bytes	browser-screen layout
Accessible semantic structure	`/accessibilityTree`	roles, names, states, children	that inaccessible controls do not exist
Several representations together	`/snapshot`	two or more requested formats	that the formats agree automatically
Schema-shaped extraction	`/json`	model-produced JSON	deterministic parsing or factual truth
Multiple pages over time	`/crawl`	asynchronous crawl results	current unlimited throughput

/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.

Completion contract	Good for	Failure it prevents
`waitUntil: "domcontentloaded"`	server-rendered page with small client enhancement	waiting for irrelevant long-lived connections
`waitUntil: "networkidle0"`	bounded application that becomes quiet	capturing before dependent requests finish
`waitForSelector: "#results"`	a known state transition	treating the application shell as the result
fixed delay	almost nothing by itself	none; it only moves the race
application assertion	login, checkout, dashboard state	proving the wrong authenticated or error state

A useful row therefore separates navigation from success:

json21 lines1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "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
  }
}
Line 21, Column 1JSON

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.

Fresh measurement	Result
Cloudflare response status	200
Client-observed elapsed time	1,418 ms
`X-Browser-Ms-Used`	207.706 ms
API response bytes	199
Returned Markdown characters	167
Expected heading present	yes

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:

bash

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"}'

Line 5, Column 1Shell Script

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.

Cost or limit surface	Workers Free	Workers Paid default
Browser time	10 minutes/day	10 hours/month, then $0.09/hour
Quick Action rate	1 request/10 seconds	10 requests/second
Session browsers	3 concurrent	120 concurrent limit
Included session concurrency for pricing	3	10 monthly-average daily peak
New session instances	1 every 20 seconds	1/second
Inactivity timeout	60 seconds	60 seconds
Configurable inactivity timeout	up to 10 minutes	up to 10 minutes

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();
}

Line 9, Column 1JavaScript

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:

capture rendered HTML plus the representation used downstream;
retain the final URL after redirects;
hash both outputs;
validate required links or fields against the HTML;
label model-extracted JSON as derived;
store a screenshot when the claim is visual;
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.

Evidence status	Browser example	What can be claimed
observed	screenshot visibly contains an error banner	the banner was visible in that capture
derived	model maps rendered page into a product schema	the model produced fields from that input
specified	Cloudflare documents a request limit	the published contract states the limit
implemented	catalogue row and adapter exist in code	this version contains the path
deployed	production endpoint accepts the row	the deployed version exposes it
reproduced	controlled call returns the expected representation	the tested input worked at that time
externally attested	named operator reports a failure or use	that operator reported that experience

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:

text

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

Line 3, Column 1Plain Text

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:

Boundary	Required control
scheme	allow `https:`; reject `file:`, `data:`, local protocols
destination	resolve DNS and reject private, loopback, link-local and metadata addresses
redirects	revalidate every redirect target
subresources	block or constrain hosts when the task permits
credentials	declare exactly which cookies, headers or HTTP auth may leave
scripts	prohibit untrusted catalogue rows from injecting code
downloads	disable or quarantine with size and type limits
duration	bounded navigation, selector and overall operation timeouts
wallet	per-invocation browser-ms budget and caller quota
output	byte limit, format validation, hashing and secret scan

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:

json

{
  "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}
}

Line 14, Column 1JSON

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.

Requirement	Prefer	Reason
one URL to Markdown	Quick Action	bounded request and direct browser-time receipt
screenshot plus HTML	`/snapshot`	representations share one capture
named CSS fields	`/scrape`	selector contract is explicit
multi-page site collection	`/crawl`	asynchronous job semantics
click through a flow	Puppeteer/Playwright	stateful interaction
persistent authenticated workspace	reusable session	cookies and state are intentional
stable public JSON endpoint	ordinary `fetch()`	no browser evidence is needed

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.

References (21)

Browser Run Quick Actions overview — Cloudflare“Quick Actions are a set of REST API endpoints that provide common browser automation tasks.”
/markdown — Extract Markdown from a webpage — Cloudflare“The `/markdown` endpoint retrieves a webpage's content and converts it into Markdown format.”
/snapshot — Capture multiple page formats — Cloudflare“The `/snapshot` endpoint combines multiple formats into a single request, so you do not need to call each endpoint separately.”
/content — Fetch rendered HTML — Cloudflare“For JavaScript-heavy pages or Single Page Applications (SPAs), the default page load behavior may return empty or incomplete results.”
/accessibilityTree — Capture the accessibility tree — Cloudflare“For faster responses, advanced users can use `waitForSelector` to wait for a specific element instead of waiting for all network activity to stop.”
/scrape — Scrape HTML elements — Cloudflare“The `userAgent` parameter does not bypass bot protection. Requests from Browser Run will always be identified as a bot.”
/json — Capture structured data using AI — Cloudflare“In this example, Browser Run first calls Anthropic's Claude Sonnet 4 model.”
/crawl — Crawl web content — Cloudflare“Crawl jobs have a maximum run time of seven days. If a job does not finish within this time, it will be cancelled due to timeout.”
Browser Run pricing — Cloudflare, Apr 21, 2026“The `X-Browser-Ms-Used` header, which is returned in every Quick Actions response, reports browser time used for the request (in milliseconds).”
Browser Run limits — Cloudflare, May 20, 2026“Crawl jobs per day | 5 per day”
Puppeteer on Browser Run — Cloudflare“The `keep_alive` option sets the time in milliseconds to keep the browser open after the last activity.”
/screenshot — Capture a screenshot — Cloudflare“Provide valid session cookies to access pages that require login:”
miscsubjects architecture — GitHub“Tooling as data. The capability catalogue is rows in SQL, not tool schemas in a prompt.”
Cloudflare crawl endpoint — Hacker News, Mar 11, 2026“[0] seems to suggest even paid plans are effectively limited to 500 web pages per day, right?”
BUG: browser rendering browser.close() hangs — GitHub — cloudflare/workers-sdk, Jul 13, 2025“Like it says, `browser.close()` hangs in dev, in both vite and wrangler. It works fine in production, but this is a blocker for dev.”
Cloudflare Browser Rendering API (Code 7003/7000) Failure in Worker — GitHub — cloudflare/workers-sdk, Oct 3, 2025“Despite verified API token permissions and Account ID, the API consistently returns a 400 error.”
Browser Rendering /crawl API: Markdown converter incorrectly resolves root-relative image URLs — GitHub — cloudflare/workers-sdk, Apr 10, 2026“The `/crawl` endpoint's HTML-to-markdown converter incorrectly resolves root-relative image paths (paths starting with `/`) as page-relative paths, producing broken image URLs in the markdown output.”
Perplexity is using stealth, undeclared crawlers to evade no-crawl directives — Hacker News, Aug 4, 2025“PS: perplexity is using cloudflare browser rendering to scrape websites”
Cloudflare crawl endpoint — Hacker News, Mar 12, 2026“I built a CLI wrapper for the Browser Rendering REST API — covers all 9 endpoints including /crawl. Two Bun scripts, zero dependencies”
ChatGPT won't let you type until Cloudflare reads your React state — Hacker News, Mar 30, 2026“hence i am just using cloudflare remote browser rendering.”
Fresh first-party Browser Run /markdown receipt — miscsubjects.com, Jul 26, 2026“Status 200; X-Browser-Ms-Used 207.706 ms; client elapsed 1418 ms.”

The system

Messaging

Ads and leads

Devices

Industries

Explore

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