EN PT ID

Cloudflare Browser Run /script: Custom Browser Automation

November 21, 2026 · 11 min read · Social Media Tools

On November 20, 2026, Cloudflare added an endpoint that lets you run your own browser automation code with a single HTTP request. You submit a JavaScript function, Cloudflare acquires a real browser, runs your function against it in an isolated Worker, and returns a JSON result. No Worker to deploy, no browser to babysit, no session to hold open.

That is the headline. It is also the part that is easy to get wrong, because the same release contains a set of rules about who closes the session, when it stops costing money, and which error code you get when you get the ordering wrong. Get those wrong and a one-request workflow quietly turns into a bill that grows every minute.

This is a look at what actually shipped, read from Cloudflare's own changelog and API documentation, for people whose job is capturing social content - posts, threads, articles that live behind a login or render only after JavaScript runs.

What shipped on November 20, 2026

The changelog entry is short: "Run custom scripts in Browser Run with /script". The documentation underneath it is where the useful detail lives.

EndpointWhat it doesSession
POST /scriptRuns your function and lets Browser Run acquire the browserCreates one; the session and target IDs come back in response headers
POST /script/<sessionId>Runs a follow-up function in a session you already holdReuses the session, so pages, cookies and navigation history survive between calls

The request body always needs code, a JavaScript function expression. You choose the runner with library: playwright, puppeteer, or omit it and use the raw Chrome DevTools Protocol. The function is invoked with a library-specific object - Playwright gets { page, context, browser, request }, Puppeteer gets { page, browser, request }, and CDP gets { send, on, off, sessionId, targetId, request } instead.

Your return value is turned into the response body. A JSON-serializable value comes back as { "success": true, "result": ... }. Return null or undefined and you get result: null. Return a Response with a JSON body and Browser Run keeps your headers but rewrites the status to 200. Return binary data and it is passed through untouched with its own content type.

The session is yours to close, and that is the whole story

This is the part worth reading twice.

Neither endpoint closes the session after your script runs. Not on success, not on a compile error, not on an exception, not on a timeout. Cloudflare closes the session in exactly one case: when /script fails after acquiring the browser but before your script starts - and in that case you never received the session ID anyway.

Once your script starts, the session keeps running and keeps counting toward your browser hours until its idle timeout expires. That timeout is keep_alive, which defaults to 60,000 milliseconds (one minute) and can be set anywhere between 10,000 and 1,200,000 milliseconds (twenty minutes).

So the arithmetic is: a request that fails at 14:00 and is never closed keeps billing until 14:01 at the earliest. A request that fails at 14:00 with keep_alive=120000 keeps billing until 14:02. If you are running a loop over fifty URLs and four of them throw, you now have four open browsers until they time out on their own.

Closing is explicit. Either call DELETE /devtools/browser/<sessionId>, or call browser.close() at the end of your last script. Disconnecting is not enough - dropping a WebSocket or calling puppeteer.disconnect() does not close the browser, because the browser never belonged to your process in the first place.

# 2. Continue the same session, then close it.
#    /script NEVER closes the session for you - not on success, not on a
#    422. An open session keeps running and keeps billing until keep_alive
#    expires, which is 60 seconds by default and 20 minutes at the maximum.

curl -s -X POST \
  "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-run/script/SESSION_ID" \
  -H "Authorization: Bearer YOUR_CF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "async function ({ page }) { return { url: page.url() }; }",
    "library": "playwright",
    "targetId": "TARGET_ID"
  }'

# Close it explicitly, or the browser stays alive and stays billable.
curl -s -X DELETE \
  "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-run/devtools/browser/SESSION_ID" \
  -H "Authorization: Bearer YOUR_CF_TOKEN"

One more trap in the same family: Browser Run closes a browser for you on task completion only if it never became a session. Once you are in session mode, the browser outlives the request that created it.

What it costs, and where Cloudflare's own pages disagree

Browser hours are shared across every method - Quick Actions, Puppeteer, Playwright, CDP and custom scripts all draw from the same pool. Workers Free gives you 10 minutes of browser time per day. Workers Paid gives you 10 hours per month, then $0.09 per additional hour.

Concurrent browsers are billed separately, and this is where Cloudflare's documentation contains a genuine inconsistency that will cost you if you read only one of the two pages.

SourceWorkers Paid concurrent browsersPage date
Limits page200 per accountModified 14 Oct 2026
Pricing page10 browsers averaged monthly, then $2.00 per additional browserModified 20 Nov 2026

The Pricing page is the newer one and it is also the one that tells you how the number is actually calculated: Cloudflare records your daily peak concurrency and averages those peaks across the month. So a workload that spikes to 40 browsers for one afternoon and sits at 2 for the rest of the month is billed on something close to the monthly average, not on 40.

The Limits page, which was last touched six days before the pricing page, still says 200 per account. Read together, the honest reading is: 200 is the hard ceiling, 10 is the included allowance, and everything above 10 is billed on the monthly average. If your workflow really does run 200 concurrent browsers every day, the $2.00-per-browser line is the one that shows up on your invoice.

Two more billing details worth knowing. First, browser hours are billed for the session lifetime, not per request - a session that sits idle for nineteen minutes is nineteen minutes of billable time even if you only made one call. Second, failed requests are generally not charged: a Quick Action that fails with a waitForTimeout error does not bill the session.

You can see what you are spending as you go. Every Quick Action and /script response carries an X-Browser-Ms-Used header. For /script it reports the cumulative browser time since the session began, not just this call - which is exactly the number you want, because it is the number that decides whether you closed the session in time.

Timeouts come in two layers, and they fail differently

Your timeout field caps the whole script run, excluding browser acquisition time. The default is 60 seconds and the maximum is 120 seconds. But Cloudflare does not pass your timeout down into Playwright or Puppeteer, so calls inside your script keep their library defaults - and in both libraries page.goto() and the waitFor* methods time out after 30 seconds.

Which one fires first decides the error code you get:

That distinction matters because a 408 means "you asked for too little" and a 422 means "the browser gave up first". If you want a slow page to load, raise the library timeout inside your script and keep it below your timeout, so your script can still catch the failure and return something useful.

# 1. One request, one browser, one structured result.
#    /script executes your function in an isolated Worker attached to a real
#    browser session, so there is nothing to deploy before it runs.

curl -i -X POST \
  "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-run/script?keep_alive=120000" \
  -H "Authorization: Bearer YOUR_CF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "async function ({ page }) { await page.goto(\"https://example.com/article\"); return { title: await page.title(), url: page.url() }; }",
    "library": "playwright",
    "timeout": 45000
  }'

# The session lives in the response headers, not in the body:
#   cf-browser-session-id:  SESSION_ID
#   cf-browser-target-id:   TARGET_ID
#   X-Browser-Ms-Used:      4210

The full error table is worth having nearby: 400 for invalid parameters, 401 for missing auth, 404 for a session or target that does not exist, 408 for your run timeout, 410 for a closed session, 413 for a body over 10 MiB, 422 for a script that failed to compile or threw, 429 for a rate or concurrency limit, 503 when no browser is available. A 422 also fires when you await a promise that can never resolve, so bound your waits.

Three ways to call it, and one way that will bite you

MethodWhat it needsGood for
REST APIAn API token with the Browser Run - Edit permissionCalling from anywhere, including your own scripts
Workers bindingA browser binding named BROWSER, no tokenRunning inside a Worker you already deploy
Script StudioOnly the dashboardTrying a script interactively before you call the API

The Workers binding is the cleanest path if you already run a Worker: call env.BROWSER.script() with no API token at all. The SDK names are worth noting because they are not the same as the REST path - in the Python SDK the body timeout field is called api_timeout.

The way that will bite you is local development. script() is not supported in local mode. If you run wrangler dev and call it, you get an error, not a browser on your laptop. Use npx wrangler dev --remote, or set "remote": true in the browser binding configuration. This differs from Quick Actions, where local mode works and runs against a Chrome instance on your machine.

Kitesurf: a different browser with different rules

There is a second browser backend. ?browser=kitesurf runs your function on Kitesurf, Cloudflare's stateless browser built for AI agents. It is faster and cheaper because it does not ship a full Chromium engine - it trades away tabs, themes, extensions and pixel-perfect rendering for scalability.

Three restrictions apply, and each one returns a 400 if you break it. Only the CDP runner is supported, so setting library is an error. Launch options do not apply, so sending keep_alive, recording or lab together with browser is an error. And no reusable session is created: the response has no session headers and cannot be continued with /script/<sessionId>. Kitesurf also follows its own pricing rather than the browser-hours table above, and it is currently free in beta.

Kitesurf is also not right for authenticated sessions. It cannot negotiate a bot-challenge handshake with real TLS fingerprints, and it is not built for long-running authenticated sessions that need persistent state. For signing into an account and capturing what is behind the login, use the default Chromium browser.

Running several scripts at once in one session

Requests to the same session and target are not serialised. Two overlapping runs against the same page will interfere with each other - one navigates while the other reads. To run concurrently inside one session, give each run its own target: create an extra page with the DevTools Browser Targets create API, then pass that target ID as targetId to /script/<sessionId>. Pages created this way live in the session's default context, so they persist across runs and can be targeted again later.

One related detail: /script always pins the run to the session's first page and returns that target in the cf-browser-target-id header. On /script/<sessionId> there is no fallback to another page when the target you named is not open. A 404 there usually means your target ID is stale, not that the session died.

Where this fits in a social content workflow

For anyone archiving social content, the appeal of /script is specific: it removes the deployment step between "I want this page" and "I have this page". Quick Actions already gave you /content, /markdown, /screenshot and /scrape in one request each, and the /snapshot endpoint added multiple formats from one page load. What /script adds is the multi-step case - sign in, expand the replies, click through to the quoted post, wait for the lazy images, then extract - as one request instead of a chain of them, without writing a Worker.

The honest caveat is that the endpoint is a browser, and a browser is identifiable. Cloudflare's own documentation states that requests from Browser Run will always be identified as a bot, and that a custom userAgent does not change that. Sites that block datacenter traffic will still block you. That is the same constraint you have with any headless capture, and it is the reason an archive you own is worth more than a capture you rent.

# 3. Attach provenance to the capture, then keep your own copy of the
#    source-side record. The capture time belongs next to the content.

printf '%s\n' \
  "source_url: https://example.com/article" \
  "captured_at: 2026-11-21T09:00:00Z" \
  "browser_ms_used: 4210" \
  "session_id: SESSION_ID" \
  | tee archive/article-provenance.yml

# ThreadGrab keeps the profile record as JSON, with the fetch time attached.
curl -s "https://threadgrab.com/api/profile/USERNAME" \
  -H "Accept: application/json" \
  -o archive/USERNAME-profile.json

So the practical workflow is: use /script to get the rendered content you could not get otherwise, close the session explicitly, and write down the capture time and the source URL next to what you saved. The content is the asset. The browser session is the tool that got it, and it is billed until you say so.

FAQ

Do I need to deploy a Worker to use the /script endpoint?

No. Browser Run executes your submitted function in an isolated Worker connected to the browser session, so there is nothing to deploy before it runs. You can also call env.BROWSER.script() from a Worker you already have, with no API token, or try scripts from the Script Studio page in the Cloudflare dashboard.

Does the /script endpoint close the browser session automatically?

No. Neither endpoint closes the session once your script has started - not on success, not on an error, not on a timeout. The session keeps running and keeps counting toward your browser hours until you close it with a DELETE on the devtools browser endpoint or call browser.close(), or until the keep_alive idle timeout expires (60 seconds by default, up to 20 minutes).

What is the difference between a 408 and a 422 error?

A 408 means your own timeout was lower than the library default, so the run limit interrupted the slow call. A 422 means the library timeout fired first - usually the 30 second default on page.goto() - and your script threw. Raise the library timeout inside your script and keep it below your timeout to get the behaviour you expect.

How much does a custom script cost?

Browser hours are shared across all Browser Run methods. Workers Free includes 10 minutes per day; Workers Paid includes 10 hours per month and then charges $0.09 per additional hour. Concurrent browsers are billed separately, and note that you are billed for the session lifetime rather than per request, so an unclosed session keeps costing money until it idles out.

Can I run custom scripts locally during development?

No. The script() method is not supported in local development mode. Use npx wrangler dev --remote, or set remote to true in your browser binding configuration. This differs from Quick Actions, which do work locally against a Chrome instance on your own machine.

Is Kitesurf the same as the default browser?

No. Kitesurf is Cloudflare's stateless browser for AI agents, and it follows different rules: only the CDP runner is supported, launch options do not apply, and no reusable session is created, so a Kitesurf run cannot be continued. It also cannot negotiate a bot-challenge handshake with real TLS fingerprints, which rules it out for long-running authenticated sessions.

Will a custom user agent stop sites from blocking Browser Run?

No. Cloudflare states that requests from Browser Run will always be identified as a bot and that the configurable user agent does not bypass bot protection. Destination servers that want to block Browser Run can identify it, so headless capture remains a constrained approach on sites that block datacenter traffic.

The bottom line

Cloudflare's /script endpoint is a real change for anyone who needs multi-step browser work without running infrastructure: your Playwright or Puppeteer code goes out as one HTTP request and comes back as JSON. Three things are worth internalising before you rely on it.

First, you own the session. It never closes itself, it bills until it idles out, and closing it is a separate call. Second, the timeout you set and the timeout your library uses are different numbers that fail with different status codes. Third, the concurrency allowance is documented in two places that disagree - use the pricing page, because it is the newer one and it explains how the average is calculated.

And keep your own copy of what you captured. A browser session is rented time on Cloudflare's infrastructure; the archive is the part that stays yours.

Archive the rendered page, not just the URL

ThreadGrab saves public X threads, Bluesky posts and LinkedIn articles as clean Markdown and JSON, with the capture time attached. A browser session can fetch the rendered page; the archive is what still belongs to you afterwards.

Try ThreadGrab →

Primary sources