When should a team use Browser Run Quick Actions such as /screenshot and /pdf instead of driving Puppeteer, and how is a Quick Action called?
answer
- one request, one result
- REST token or binding method
- billed for browser hours only
- results cached for a few seconds
- crawl is a job, not a call
basics
~20 sUse Quick Actions when one request describes the whole job, such as screenshotting a URL or rendering invoice HTML to PDF: POST to the REST endpoint with an API token, or call env.BROWSER.quickAction() from a Worker.
solid answer
~50 sQuick Actions are stateless endpoints under `/accounts/<accountId>/browser-run/`, among them `/screenshot`, `/pdf`, `/content`, `/markdown`, `/scrape`, `/links`, `/snapshot` and `/crawl`. Each takes a `url` or `html` plus options such as `viewport`, `gotoOptions`, `screenshotOptions` or `pdfOptions`. From outside a Worker they need an API token with the `Browser Run - Edit` permission; from a Worker, `env.BROWSER.quickAction("pdf", { html })` needs no token but a compatibility date of 2026-03-24 or later. They are billed for browser hours only, not concurrent browsers, and limited by request rate (30 per second on Workers Paid). Choose Puppeteer or Playwright when the job needs several steps, a session kept across requests, or control the options do not offer. Two traps: results are cached for 5 seconds by default (`cacheTTL`, up to 86400, `0` disables), and `/crawl` is REST-only and asynchronous, returning a job ID to poll.
code
typescript · 15 linesinterface Env {
BROWSER: BrowserRun;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const invoiceHtml = await request.text();
const pdf = await env.BROWSER.quickAction("pdf", {
html: invoiceHtml,
cacheTTL: 0,
});
console.log("browser ms", pdf.headers.get("X-Browser-Ms-Used"));
return pdf;
},
};go deeper
Recall the two ways in: a REST call with a Browser Run - Edit token, or env.BROWSER.quickAction() from a Worker with no token.
Explain the billing and limit difference from Browser Sessions, the url-or-html body, and the options that shape a PDF or screenshot.
Show you know the traps: the 5-second result cache, quickAction() failing in local mode, 422s cured by actionTimeout, and crawl being an asynchronous job.
Decide which jobs stay on Quick Actions, which justify maintaining browser-session code, and how the team watches X-Browser-Ms-Used to keep cost visible.
## Two ways to drive a browser Browser Run offers two integration methods, and the choice decides what a team writes, what it pays for and which limits bind it. | | Quick Actions | Browser Sessions | |---|---|---| | What you send | one HTTP request or `quickAction()` call | a script driving Puppeteer, Playwright or CDP | | Browser lifecycle | managed by Browser Run | yours: launch, reuse, close | | Billing | browser hours | browser hours plus concurrent browsers | | Main limit | requests per second (30 on Workers Paid, 1 every 10 seconds on Free) | concurrent browsers and new browsers per second | | State across requests | none | a session can be kept and reused | For the invoice-and-preview scenario, both jobs fit a single request: "render this HTML to PDF" and "screenshot this URL at 1200 by 630". That is the Quick Actions case. A job that logs in by clicking, walks several pages, or must reuse one browser for many requests is a Browser Sessions job. ## Calling a Quick Action over REST Each action is a `POST` to `https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/<action>` with a JSON body. The body must carry exactly one of `url` or `html`. The caller authenticates with an API token holding the **Browser Run - Edit** permission. This suits a backend outside Cloudflare, a CI job, or a one-off script. ## Calling from a Worker A Worker with a `browser` binding calls `env.BROWSER.quickAction(action, options)` and gets a `Response` back. No token is involved. Two requirements apply: - a `compatibility_date` of **2026-03-24** or later; - local development: `quickAction()` is not implemented by the local browser binding, so under plain `wrangler dev` it fails with `The RPC receiver does not implement the method "quickAction"`; it works against the real service with the binding in remote mode, which uses the account's quota. ## Options that matter for invoices and previews - `html` renders a string you built, so invoice HTML never has to be reachable at a URL; - `pdfOptions` passes page format, margins, header and footer templates; - `screenshotOptions` passes `type`, `fullPage`, `clip` and `quality` (which needs `jpeg` or `webp`, since the default `png` rejects it with a 400); - `viewport` overrides the default 1920 by 1080; - `gotoOptions.waitUntil` chooses when the page counts as loaded: `domcontentloaded` by default, `networkidle0` or `networkidle2` for pages that render with JavaScript; - `actionTimeout` gives a slow screenshot or PDF more time when the response is a 422; - `cacheTTL` controls the result cache, 5 seconds by default, up to 86400, and `0` turns it off. The cache matters for link previews: a second identical request inside the window returns the first result instead of a fresh render. ## Reading cost and errors Every Quick Actions response carries `X-Browser-Ms-Used`, the browser time that request consumed, which is the number to log when estimating the bill. A `429` means the request rate was exceeded; its `Retry-After` header says how long to wait. ## /crawl is a different shape `/crawl` follows links from a starting URL and is available through the REST API only. It is asynchronous: 1. a `POST` starts a job and returns its ID; 2. `GET /crawl/<id>` reports a `status` such as `running`, `completed` or `errored`, or a Queues event subscription pushes lifecycle events; 3. results stay available for 14 days. On Workers Free it is capped at 5 crawl jobs a day and 100 pages a crawl. Which sites a team may crawl, and how, is a matter for the material on crawler etiquette. ## Pages behind a login Every Quick Actions endpoint accepts three ways to render a page that needs authentication: `cookies` for a session cookie, `authenticate` for HTTP Basic credentials, and `setExtraHTTPHeaders` for a bearer token. The credentials travel in the request body, so they belong in the backend or Worker making the call, never in browser code. For a customer's public page, used for a link preview, none of them is needed. ## Choosing quickly - One page in, one artefact out, no clicking: a Quick Action. - A sequence of steps, a form to fill, or state carried between pages: a Puppeteer or Playwright session. - Many requests a second against the same few sites: a session reused across requests, or Quick Actions within the request rate. - The call comes from outside Cloudflare: the REST API with a scoped token.
- A Worker calls quickAction() and gets 'The RPC receiver does not implement the method quickAction' only on a developer laptop; why?The local browser binding under `wrangler dev` does not implement Quick Actions. The call works against the real service when the binding runs in remote mode, which spends the account's quota, or after deployment. Puppeteer and Playwright code, by contrast, runs against a local Chrome.
- Why does a Quick Actions screenshot sometimes show a page before its JavaScript has drawn the content?By default `gotoOptions.waitUntil` is `domcontentloaded`, which fires before scripts finish rendering. Set it to `networkidle0` or `networkidle2`, or use `waitForSelector` for the element you need, and raise `actionTimeout` if the capture itself then returns a 422.
- Quick Actions are billed per concurrent browser like Puppeteer sessions
- A Worker must pass an API token to quickAction()
- Every Quick Actions request renders fresh, with no caching
- The crawl endpoint can be called from a Worker's quickAction()
- Quick Actions suit multi-step logins that click through forms
Assumes Browser Run as of 2026-10-10: the product was renamed from Browser Rendering on 2026-04-15, the quickAction() binding method arrived on 2026-05-28, and the Paid Quick Actions rate rose to 30 requests per second on 2026-08-20.