Cloudflare Browser Run /script: Otomatisasi Browser
Pada 20 November 2026, Cloudflare menambahkan endpoint yang memungkinkan Anda menjalankan kode otomatisasi browser sendiri dengan satu permintaan HTTP. Anda kirim sebuah fungsi JavaScript, Cloudflare mendapat browser sungguhan, menjalankan fungsi Anda di terhadapnya dalam sebuah Worker terisolasi, lalu mengembalikan hasil JSON. Tidak ada Worker yang perlu dideploy, tidak ada browser yang perlu dijaga, tidak ada sesi yang harus dibiarkan terbuka.
ITulah judulnya. Dan itu juga bagian yang mudah keliru, karena rilis yang sama berisi seperangkat aturan tentang siapa yang menutup sesi, kapan biaya itu berhenti, dan kode error apa yang Anda terima saat urutan salah. Salah menerapkan aturan itu akan mengubah alur satu permintaan secara diam-diam menjadi tagihan yang bertambah setiap menit.
Artikel ini melihat apa yang benar-benar dirilis, dibaca langsung dari changelog dan dokumentasi API Cloudflare, untuk orang yang pekerjaannya adalah mengarsipkan konten sosial - post, thread, dan artikel yang berada di balik login atau hanya tampil setelah JavaScript menjalankan.
Apa yang rilis pada 20 November 2026
Entri changelognya singkat: "Run custom scripts in Browser Run with /script". Yang berguna ada di dokumentasi di bawahnya.
| Endpoint | Apa yang dikerjakan | Sesi |
|---|---|---|
POST /script | Menjalankan fungsi Anda dan membiarkan Browser Run mendapat browser sendiri | Membuat satu sesi; ID sesi dan target kembali di header respons |
POST /script/<sessionId> | Menjalankan fungsi lanjutan pada sesi yang sudah Anda pegang | Memakai ulang sesi, sehingga halaman, cookie, dan riwayat navigasi bertahan antar panggilan |
Badan permintaan selalu memerlukan code, yaitu ekspresi fungsi JavaScript.
Anda memilih runner dengan library: playwright,
puppeteer, atau menghilangkannya untuk memakai Chrome DevTools Protocol
mentah. Fungsi tersebut dipanggil dengan objek khusus per pustaka - Playwright menerima
{ page, context, browser, request }, Puppeteer menerima
{ page, browser, request }, dan CDP menerima
{ send, on, off, sessionId, targetId, request } sebagai gantinya.
Nilai yang Anda kembalikan menjadi badan respons. Nilai yang bisa diserialisasi ke JSON
kembali sebagai { "success": true, "result": ... }. Kembalikan
null atau undefined, Anda mendapat result: null.
Kembalikan sebuah Response dengan badan JSON, Browser Run mempertahankan
header Anda tetapi menulis ulang statusnya menjadi 200. Kembalikan data biner, data itu
diteruskan apa adanya dengan content type-nya sendiri.
Sesi milik Anda untuk ditutup, dan itu inti semuanya
Bagian ini layak dibaca dua kali.
Tidak ada satu pun dari kedua endpoint yang menutup sesi setelah skrip Anda berjalan.
Bukan saat sukses, bukan saat error kompilasi, bukan saat exception, bukan saat timeout.
Cloudflare menutup sesi dalam tepat satu kasus: ketika /script gagal
setelah mendapatkan browser tapi sebelum skrip Anda mulai - dan pada kasus
itu Anda memang tidak pernah menerima ID sesi.
Setelah skrip Anda mulai, sesi terus berjalan dan terus dihitung sebagai jam browser
Anda sampai batas waktu idle habis. Batas waktu itu adalah keep_alive, yang
default-nya 60.000 milidetik (satu menit) dan bisa diatur antara 10.000 sampai 1.200.000
milidetik (dua puluh menit).
Jadi hitungannya begini: permintaan yang gagal pukul 14.00 dan tidak pernah ditutup
tetap berbiaya sampai pukul 14.01 paling cepat. Permintaan yang gagal pukul 14.00 dengan
keep_alive=120000 tetap berbiaya sampai pukul 14.02. Kalau Anda menjalankan
loop atas lima puluh URL dan empat di antaranya melempar exception, sekarang ada empat
browser terbuka sampai mereka kehabisan waktu dengan sendirinya.
Penutupan bersifat eksplisit. Panggil DELETE /devtools/browser/<sessionId>,
atau panggil browser.close() di akhir skrip terakhir Anda. Putus koneksi saja
tidak cukup - meninggalkan WebSocket atau memanggil
puppeteer.disconnect() tidak menutup browser, karena browser itu memang tidak
pernah milik proses Anda.
# 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"
Perangkap lain di keluarga yang sama: Browser Run menutup browser untuk Anda saat tugas selesai hanya jika browser itu tidak pernah berubah menjadi sesi. Begitu sudah dalam mode sesi, browser itu bertahan melewati permintaan yang membuatnya.
Biayanya berapa, dan di mana halaman Cloudflare sendiri saling berbeda
Jam browser dipakai bersama oleh semua metode - Quick Actions, Puppeteer, Playwright, CDP, dan skrip kustom semuanya menarik dari reservoir yang sama. Workers Free memberi 10 menit waktu browser per hari. Workers Paid memberi 10 jam per bulan, lalu menagih US$ 0,09 per jam tambahan.
Browser yang berjalan bersamaan ditagih secara terpisah, dan di sinilah dokumentasi Cloudflare memuat ketidakkonsistenan yang sungguhan dan bisa memakan biaya kalau Anda hanya membaca satu dari dua halaman itu.
| Sumber | Browser bersamaan di Workers Paid | Tanggal halaman |
|---|---|---|
| Halaman limits | 200 per akun | Diperbarui 14 Okt 2026 |
| Halaman pricing | 10 browser rata-rata bulanan, lalu US$ 2,00 per browser tambahan | Diperbarui 20 Nov 2026 |
Halaman pricing adalah yang lebih baru, dan juga yang memberitahu bagaimana angka itu sebenarnya dihitung: Cloudflare mencatat puncak konkurensi harian Anda lalu mengambil rata-rata puncak-puncak itu sepanjang bulan. Jadi beban kerja yang melonjak ke 40 browser pada satu sore lalu berada di angka 2 sepanjang sisa bulan ditagih berdasarkan sesuatu yang mendekati rata-rata bulanan, bukan 40.
Halaman limits, yang terakhir diubah enam hari sebelum halaman pricing, masih menyebutkan 200 per akun. Dibaca bersama, pembacaan yang jujur adalah: 200 adalah batas keras, 10 adalah kuota yang termasuk, dan semua di atas 10 ditagih berdasarkan rata-rata bulanan. Kalau alur kerja Anda benar-benar menjalankan 200 browser bersamaan setiap hari, baris US$ 2,00 per browser itulah yang muncul di tagihan Anda.
Detail penagihan lain yang perlu diketahui. Pertama, jam browser ditagih berdasarkan
umur sesi, bukan per permintaan - sesi yang menganggur selama sembilan belas menit
adalah sembilan belas menit waktu yang bisa ditagih, meski Anda hanya melakukan satu
panggilan. Kedua, permintaan yang gagal umumnya tidak ditagih: sebuah Quick Action yang
gagal dengan error waitForTimeout tidak menagih sesi.
Anda bisa melihat pengeluaran saat berjalan. Setiap respons Quick Action dan
/script membawa header X-Browser-Ms-Used. Untuk
/script header itu melaporkan waktu browser kumulatif sejak sesi dimulai,
bukan hanya panggilan ini - dan itu persis angkanya yang Anda butuhkan, karena itu yang
menentukan apakah Anda menutup sesi tepat waktu.
Timeout datang dalam dua lapis, dan gagal dengan cara berbeda
Field timeout membatasi seluruh eksekusi skrip, tidak termasuk waktu
pengambilan browser. Default-nya 60 detik dan maksimalnya 120 detik. Tapi Cloudflare tidak
meneruskan timeout Anda ke dalam Playwright atau Puppeteer, sehingga
panggilan di dalam skrip Anda tetap memakai default pustaka - dan di kedua pustaka,
page.goto() serta metode waitFor* kehabisan waktu setelah 30
detik.
Yang mana yang lebih dulu menentukan kode error yang Anda terima:
- Jika
timeoutAnda lebih kecil dari timeout pustaka, batas eksekusi memutus panggilan lambat itu dan permintaan gagal dengan408. - Jika
timeoutAnda lebih besar, timeout pustaka yang lebih dulu menyala, skrip Anda melempar sesuatu sepertiNavigation timeout of 30000 ms exceeded, dan permintaan gagal dengan422.
Perbedaan ini penting karena 408 berarti "Anda meminta terlalu sedikit" sedangkan 422
berarti "browser menyerah lebih dulu". Kalau Anda ingin halaman lambat termuat, naikkan
timeout pustaka di dalam skrip dan jagalah tetap di bawah timeout Anda, supaya
skrip masih bisa menangani kegagalan itu dan mengembalikan sesuatu yang berguna.
# 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
Tabel error lengkapnya layak dijaga di dekat: 400 untuk parameter tidak valid, 401 untuk autentikasi hilang, 404 untuk sesi atau target yang tidak ada, 408 untuk timeout eksekusi Anda, 410 untuk sesi yang sudah ditutup, 413 untuk badan lebih dari 10 MiB, 422 untuk skrip yang gagal kompilasi atau melempar exception, 429 untuk batas laju atau konkurensi, 503 ketika tidak ada browser yang tersedia. 422 juga menyala ketika Anda menunggu promise yang tak akan pernah resolve, jadi bataskan setiap menunggu.
Tiga cara memanggilnya, dan satu yang akan menggigit Anda
| Metode | Yang dibutuhkan | Cocok untuk |
|---|---|---|
| REST API | Token API dengan izin Browser Run - Edit | Memanggil dari mana saja, termasuk dari skrip Anda sendiri |
| Binding Workers | Binding browser bernama BROWSER, tanpa token | Berjalan di dalam Worker yang sudah Anda deploy |
| Script Studio | Hanya dasbor | Mencoba skrip secara interaktif sebelum memanggil API |
Binding Workers adalah jalur terbersih kalau Anda sudah menjalankan sebuah Worker:
panggil env.BROWSER.script() tanpa token API sama sekali. Nama-nama di SDK
perlu dicatat karena tidak sama dengan path REST - di SDK Python, field timeout
pada badan bernama api_timeout.
Yang akan menggigit Anda adalah pengembangan lokal. script() tidak didukung
dalam mode lokal. Kalau Anda menjalankan wrangler dev lalu memanggilnya, yang
Anda dapat adalah error, bukan browser di mesin Anda sendiri. Gunakan
npx wrangler dev --remote, atau setel "remote": true pada
konfigurasi binding browser. Ini berbeda dari Quick Actions, yang jalan lokal dengan
instance Chrome di mesin Anda sendiri.
Kitesurf: browser berbeda dengan aturan berbeda
Ada backend browser kedua. ?browser=kitesurf menjalankan fungsi Anda di
Kitesurf, browser stateless milik Cloudflare yang dibuat untuk agen AI. Browser ini lebih
cepat dan lebih murah karena tidak membawa mesin Chromium penuh - ia menukar tab, tema,
ekstensi, dan render pixel-perfect dengan skalabilitas.
Ada tiga pembatasan, dan masing-masing mengembalikan 400 kalau Anda
melanggarnya. Hanya runner CDP yang didukung, jadi menetapkan library adalah
error. Opsi peluncuran tidak berlaku, jadi mengirim keep_alive,
recording, atau lab bersama browser adalah error.
Dan tidak ada sesi yang bisa dipakai ulang yang dibuat: responsnya tidak punya header sesi
dan tidak bisa dilanjutkan dengan /script/<sessionId>. Kitesurf juga
mengikuti tabel harga sendiri dan saat ini gratis dalam beta.
Kitesurf juga bukan pilihan untuk sesi terautentikasi. Ia tidak bisa bernegosiasi handshake tantangan bot dengan sidik jari TLS asli, dan tidak dibangun untuk sesi terautentikasi jangka panjang yang membutuhkan state persisten. Untuk masuk ke sebuah akun dan mengarsipkan apa pun di balik login, gunakan browser Chromium bawaan.
Menjalankan beberapa skrip sekaligus dalam satu sesi
Permintaan ke sesi dan target yang sama tidak diserialisasi. Dua eksekusi yang tumpang
tindih pada halaman sama akan mengganggu satu sama lain - satu sedang bernavigasi sementara
yang lain membaca. Untuk menjalankan secara paralel di dalam satu sesi, beri setiap
eksekusi target sendiri: buat halaman tambahan dengan API pembuatan DevTools Browser Targets,
lalu kirim target ID itu sebagai targetId ke
/script/<sessionId>. Halaman yang dibuat dengan cara itu hidup di konteks
default sesi, sehingga bertahan antar eksekusi dan bisa ditargeting lagi nanti.
Detail terkait: /script selalu mem-pin eksekusi ke halaman pertama sesi
dan mengembalikan target itu di header cf-browser-target-id. Pada
/script/<sessionId> tidak ada fallback ke halaman lain ketika target
yang Anda sebut tidak terbuka. 404 di sana biasanya berarti target ID Anda sudah basi,
bukan berarti sesinya mati.
Di mana ini masuk ke alur konten sosial
Bagi siapa pun yang mengarsipkan konten sosial, daya tarik /script bersifat
spesifik: ia menghapus langkah deploy antara "saya mau halaman ini" dan "saya punya halaman
ini". Quick Actions sebenarnya sudah memberi Anda /content,
/markdown, /screenshot, dan /scrape dalam satu
permintaan masing-masing, dan endpoint /snapshot menambahkan beberapa format
dari satu kali pemuatan halaman. Yang ditambahkan /script adalah kasus banyak
langkah - masuk ke akun, buka balasan, klik ke kutipan, tunggu gambar lazy, baru ekstrak -
sebagai satu permintaan alih-alih rantai permintaan, tanpa menulis Worker.
Catatan jujurannya: endpoint ini adalah browser, dan browser itu bisa dikenali.
Dokumentasi Cloudflare sendiri menyatakan bahwa permintaan dari Browser Run selalu akan
dikenali sebagai bot dan bahwa userAgent yang bisa disesuaikan tidak
mengubah hal itu. Situs yang memblokir lalu lintas dari pusat data tetap akan memblokir
Anda. Itu batasan yang sama dengan setiap penangkapan headless, dan itulah alasan arsip
milik Anda sendiri lebih berharga daripada penangkapan yang Anda sewa.
# 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
Jadi alur praktisnya begini: gunakan /script untuk mendapatkan konten
rendered yang tidak bisa Anda dapatkan dengan cara lain, tutup sesi secara eksplisit, dan
catat waktu pengambilan serta URL sumber di samping apa yang Anda simpan. Kontennya adalah
asetnya. Sesi browser hanyalah alat yang menghasilkannya, dan itu ditagih sampai Anda
berkata berhenti.
FAQ
Apakah saya harus men-deploy Worker untuk memakai endpoint /script?
Tidak. Browser Run menjalankan fungsi yang Anda kirim di dalam Worker terisolasi yang terhubung ke sesi browser, jadi tidak ada yang perlu di-deploy sebelum eksekusi. Anda juga bisa memanggil env.BROWSER.script() dari Worker yang sudah Anda miliki, tanpa token API, atau mencoba skrip dari halaman Script Studio di dasbor Cloudflare.
Apakah endpoint /script menutup sesi browser secara otomatis?
Tidak. Tidak ada satu pun dari kedua endpoint yang menutup sesi setelah skrip Anda mulai - bukan saat sukses, bukan saat error, bukan saat timeout. Sesi terus berjalan dan terus dihitung sebagai jam browser Anda sampai Anda menutupnya dengan DELETE pada endpoint devtools browser atau memanggil browser.close(), atau sampai batas waktu idle keep_alive habis (60 detik secara default, sampai 20 menit).
Apa perbedaan antara error 408 dan error 422?
Error 408 berarti timeout Anda sendiri lebih rendah daripada default pustaka, sehingga batas eksekusi memutus panggilan lambat itu. Error 422 berarti timeout pustaka menyala lebih dulu - biasanya default 30 detik pada page.goto() - dan skrip Anda melempar exception. Naikkan timeout pustaka di dalam skrip dan jagalah tetap di bawah timeout Anda untuk perilaku yang Anda inginkan.
Berapa biaya sebuah skrip kustom?
Jam browser dipakai bersama oleh semua metode Browser Run. Workers Free mencakup 10 menit per hari; Workers Paid mencakup 10 jam per bulan lalu menagih US$ 0,09 per jam tambahan. Browser yang berjalan bersamaan ditagih terpisah, dan perhatikan bahwa Anda membayar berdasarkan umur sesi, bukan per permintaan, sehingga sesi yang tidak ditutup terus berbiaya sampai kehabisan waktu idle.
Bisakah saya menjalankan skrip kustom secara lokal saat pengembangan?
Tidak. Metode script() tidak didukung dalam mode pengembangan lokal. Gunakan npx wrangler dev --remote, atau setel remote ke true pada konfigurasi binding browser. Ini berbeda dari Quick Actions, yang jalan lokal memakai instance Chrome di mesin Anda sendiri.
Apakah Kitesurf sama dengan browser bawaan?
Tidak. Kitesurf adalah browser stateless milik Cloudflare untuk agen AI, dan ia mengikuti aturan berbeda: hanya runner CDP yang didukung, opsi peluncuran tidak berlaku, dan tidak ada sesi yang bisa dipakai ulang sehingga eksekusi Kitesurf tidak bisa dilanjutkan. Ia juga tidak bernegosiasi handshake tantangan bot dengan sidik jari TLS asli, sehingga tidak cocok untuk sesi terautentikasi jangka panjang.
Apakah user agent kustom mencegah situs memblokir Browser Run?
Tidak. Cloudflare menyatakan bahwa permintaan dari Browser Run selalu akan dikenali sebagai bot dan bahwa user agent yang bisa disesuaikan tidak melewati proteksi bot. Server tujuan yang ingin memblokir Browser Run bisa mengenaliinya, sehingga penangkapan headless tetap terbatas di situs yang memblokir lalu lintas pusat data.
Intinya
Endpoint /script dari Cloudflare adalah perubahan nyata bagi siapa pun yang
butuh kerja browser banyak langkah tanpa menjalankan infrastruktur: kode Playwright atau
Puppeteer Anda dikirim sebagai satu permintaan HTTP dan kembali sebagai JSON. Tiga hal
perlu dihafal sebelum Anda bergantung padanya.
Pertama, sesi itu milik Anda. Ia tidak pernah menutup dirinya sendiri, ia tetap berbiaya sampai kehabisan waktu idle, dan menutupnya adalah panggilan terpisah. Kedua, timeout yang Anda tetapkan dan timeout pustaka Anda adalah dua angka berbeda yang gagal dengan kode status berbeda. Ketiga, kuota konkurensi terdokumentasi di dua tempat yang saling berbeda - pakai halaman pricing, karena itu yang lebih baru dan karena menjelaskan bagaimana rata-ratanya dihitung.
Dan simpan salinan Anda sendiri dari yang Anda tangkap. Sesi browser adalah waktu sewa di infrastruktur Cloudflare; arsipnya adalah bagian yang tetap milik Anda.
Arsipkan halaman yang sudah dirender, bukan hanya URL-nya
ThreadGrab menyimpan thread publik X, post Bluesky, dan artikel LinkedIn sebagai Markdown dan JSON yang bersih, lengkap dengan waktu pengambilan. Sesi browser bisa mengambil halaman yang sudah dirender; arsipnya yang tetap milik Anda setelah itu.
Coba ThreadGrab →Sumber primer
- Cloudflare Changelog — Run custom scripts in Browser Run with /script, 20 Nov 2026
- Cloudflare Docs — Custom scripts: endpoint, argumen runner, nilai balik, tabel error dan timeout, siklus hidup sesi
- Cloudflare Docs — Limits: tabel Workers Free dan Workers Paid, konkurensi dan keep_alive, diperbarui 14 Okt 2026
- Cloudflare Docs — Pricing: jam browser, tarif browser bersamaan, X-Browser-Ms-Used, diperbarui 20 Nov 2026
- Cloudflare Docs — Get started: memilih antara Quick Actions, Browser Sessions, dan Custom scripts
- Cloudflare Docs — Kitesurf: browser stateless, hanya CDP, batasan dan apa yang tidak bisa dilakukannya
- Cloudflare Docs — Markdown endpoint: user agent kustom tidak melewati proteksi bot
- Cloudflare Blog — Kitesurf, browser stateless untuk agen AI