Cloudflare Browser Run /script: Automacao de Navegador
Em 20 de novembro de 2026, a Cloudflare adicionou um endpoint que permite executar seu proprio codigo de automacao de navegador com uma unica requisicao HTTP. Voce envia uma funcao JavaScript, a Cloudflare adquire um navegador real, executa sua funcao contra ele em um Worker isolado e devolve um resultado JSON. Sem Worker para implantar, sem navegador para babysitar, sem sessao para manter aberta.
Esse e o titulo. E tambem a parte que da para errar com facilidade, porque o mesmo lancamento contem um conjunto de regras sobre quem fecha a sessao, quando ela para de custar dinheiro e qual codigo de erro voce recebe quando inverte a ordem das coisas. Errar essas regras transforma silenciosamente um fluxo de uma requisicao em uma fatura que cresce a cada minuto.
Este e um olhar sobre o que realmente foi lancado, lido no changelog e na documentacao de API da propria Cloudflare, para quem trabalha capturando conteudo social - posts, threads e artigos que ficam atras de um login ou que so aparecem depois que o JavaScript roda.
O que foi lancado em 20 de novembro de 2026
A entrada no changelog e curta: "Run custom scripts in Browser Run with /script". A documentacao por baixo dela e onde esta o detalhe util.
| Endpoint | O que faz | Sessao |
|---|---|---|
POST /script | Executa sua funcao e deixa o Browser Run adquirir o navegador | Cria uma; os IDs de sessao e de target voltam nos cabecalhos da resposta |
POST /script/<sessionId> | Executa uma funcao seguinte em uma sessao que voce ja tem | Reaproveita a sessao, entao paginas, cookies e historico de navegacao sobrevivem entre chamadas |
O corpo da requisicao sempre precisa de code, uma expressao de funcao
JavaScript. Voce escolhe o runner com library: playwright,
puppeteer, ou omite e usa o Chrome DevTools Protocol puro. A funcao e
chamada com um objeto especifico da biblioteca - o Playwright recebe
{ page, context, browser, request }, o Puppeteer recebe
{ page, browser, request }, e o CDP recebe
{ send, on, off, sessionId, targetId, request } no lugar.
O valor que voce devolve vira o corpo da resposta. Um valor serializavel em JSON volta
como { "success": true, "result": ... }. Se voce devolver null ou
undefined, recebe result: null. Se devolver um
Response com corpo JSON, o Browser Run mantem seus cabecalhos, mas reescreve
o status para 200. Se devolver dados binarios, eles passam intactos com o proprio content
type.
A sessao e sua para fechar, e e isso tudo
Esta e a parte que vale ler duas vezes.
Nenhum dos dois endpoints fecha a sessao depois que o seu script roda. Nao no sucesso,
nao em erro de compilacao, nao em excecao, nao em timeout. A Cloudflare fecha a sessao em
exatamente um caso: quando /script falha depois de adquirir o
navegador, mas antes do seu script comecar - e, nesse caso, voce nunca recebeu o
ID da sessao de qualquer forma.
Uma vez que o script comeca, a sessao continua rodando e continua contando para as suas
horas de navegador ate o timeout de ociosidade expirar. Esse timeout e o
keep_alive, que tem padrao de 60.000 milissegundos (um minuto) e pode ser
definido entre 10.000 e 1.200.000 milissegundos (vinte minutos).
Entao a conta e esta: uma requisicao que falha as 14:00 e nunca e fechada continua
cobrando ate as 14:01, no minimo. Uma requisicao que falha as 14:00 com
keep_alive=120000 continua cobrando ate as 14:02. Se voce roda um laco sobre
cinquenta URLs e quatro delas lancam excecao, agora existem quatro navegadores abertos ate
eles expirarem sozinhos.
O fechamento e explicito. Chame DELETE /devtools/browser/<sessionId>,
ou chame browser.close() no fim do seu ultimo script. Desconectar nao basta -
abandonar um WebSocket ou chamar puppeteer.disconnect() nao fecha o navegador,
porque o navegador nunca pertenceu ao seu processo.
# 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"
Mais uma armadilha da mesma familia: o Browser Run fecha um navegador para voce quando a tarefa termina apenas se ele nunca virou sessao. Uma vez no modo de sessao, o navegador sobrevive a requisicao que o criou.
Quanto custa, e onde as proprias paginas da Cloudflare discordam
As horas de navegador sao compartilhadas por todos os metodos - Quick Actions, Puppeteer, Playwright, CDP e scripts personalizados puxam do mesmo reservatorio. O Workers Free da 10 minutos de tempo de navegador por dia. O Workers Paid da 10 horas por mes e depois cobra US$ 0,09 por hora adicional.
Os navegadores concorrentes sao cobrados separadamente, e e aqui que a documentacao da Cloudflare tem uma inconsistencia real que custa dinheiro se voce ler apenas uma das duas paginas.
| Fonte | Navegadores concorrentes no Workers Paid | Data da pagina |
|---|---|---|
| Pagina de limites | 200 por conta | Modificada em 14 de out 2026 |
| Pagina de precos | 10 navegadores na media mensal, depois US$ 2,00 por navegador adicional | Modificada em 20 de nov 2026 |
A pagina de precos e a mais nova, e tambem e a que explica como o numero e realmente calculado: a Cloudflare registra seu pico diario de concorrencia e faz a media desses picos ao longo do mes. Entao uma carga de trabalho que sobe para 40 navegadores numa tarde e fica em 2 no resto do mes e cobrado por algo proximo a media mensal, e nao por 40.
A pagina de limites, mexida seis dias antes da pagina de precos, ainda diz 200 por conta. Lidas juntas, a leitura honesta e esta: 200 e o teto maximo, 10 e a cota inclusa, e tudo acima de 10 e cobrado pela media mensal. Se o seu fluxo realmente roda 200 navegadores concorrentes todo dia, a linha de US$ 2,00 por navegador e a que aparece na sua fatura.
Mais dois detalhes de cobranca que valem conhecer. Primeiro, as horas de navegador sao
cobradas pelo tempo de vida da sessao, e nao por requisicao - uma sessao que fica
ociosa por dezenove minutos sao dezenove minutos de tempo cobravel, mesmo que voce tenha
feito apenas uma chamada. Segundo, requisicoes que falham em geral nao sao cobradas: uma
Quick Action que falha com erro de waitForTimeout nao cobra a sessao.
Voce consegue ver o que esta gastando durante a execucao. Toda resposta de Quick Action
e de /script traz o cabecalho X-Browser-Ms-Used. Para
/script ele informa o tempo de navegador acumulado desde o inicio da sessao,
nao apenas esta chamada - que e exatamente o numero que importa, porque e o numero que
decide se voce fechou a sessao a tempo.
Os timeouts vem em duas camadas, e falham de formas diferentes
O campo timeout limita toda a execucao do script, sem contar o tempo de
aquisicao do navegador. O padrao e 60 segundos e o maximo e 120 segundos. Mas a Cloudflare
nao repassa seu timeout para dentro do Playwright ou do Puppeteer, entao as
chamadas dentro do seu script mantem os padroes das bibliotecas - e nas duas, o
page.goto() e os metodos waitFor* expiram depois de 30
segundos.
Qual dos dois dispara primeiro decide o codigo de erro que voce recebe:
- Se o seu
timeoutfor menor que o timeout da biblioteca, o limite de execucao interrompe a chamada lenta e a requisicao falha com408. - Se o seu
timeoutfor maior, o timeout da biblioteca dispara primeiro, seu script lanca algo comoNavigation timeout of 30000 ms exceeded, e a requisicao falha com422.
Essa distincao importa porque 408 significa "voce pediu pouco" e 422 significa "o
navegador desistiu antes". Se voce quiser que uma pagina lenta carregue, aumente o timeout
da biblioteca dentro do script e mantenha-o abaixo do seu timeout, para que
o script ainda consiga tratar a falha e devolver algo util.
# 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
A tabela completa de erros vale ter por perto: 400 para parametros invalidos, 401 para autenticacao ausente, 404 para sessao ou target inexistente, 408 para o seu timeout de execucao, 410 para sessao ja fechada, 413 para corpo acima de 10 MiB, 422 para um script que nao compilou ou lancou excecao, 429 para limite de taxa ou concorrencia, 503 quando nao ha navegador disponivel. Um 422 tambem dispara quando voce espera por uma promessa que nunca vai ser resolvida, entao limite as esperas.
Tres formas de chamar, e uma que vai te morder
| Método | O que exige | Para que serve |
|---|---|---|
| API REST | Um token com a permissao Browser Run - Edit | Chamar de qualquer lugar, inclusive dos seus proprios scripts |
| Binding do Workers | Um binding browser chamado BROWSER, sem token | Rodar dentro de um Worker que voce ja implantou |
| Script Studio | Somente o painel | Testar um script interativamente antes de chamar a API |
O binding do Workers e o caminho mais limpo se voce ja roda um Worker: chame
env.BROWSER.script() sem token de API nenhum. Os nomes no SDK valem nota porque
nao sao iguais ao caminho REST - no SDK do Python, o campo timeout do corpo se
chama api_timeout.
A forma que vai te morder e o desenvolvimento local. O script() nao funciona
no modo local. Se voce rodar wrangler dev e chamar, recebe um erro, e nao um
navegador na sua maquina. Use npx wrangler dev --remote, ou defina
"remote": true na configuracao do binding do navegador. Isso difere das Quick
Actions, que funcionam localmente contra uma instancia do Chrome na sua propria maquina.
Kitesurf: um navegador diferente, com regras diferentes
Existe um segundo backend de navegador. ?browser=kitesurf executa sua funcao
no Kitesurf, o navegador sem estado da Cloudflare feito para agentes de IA. Ele e mais
rapido e mais barato porque nao embarca um motor Chromium completo - ele troca abas, temas,
extensoes e renderizacao pixel-perfect por escalabilidade.
Tres restricoes valem e cada uma delas devolve 400 se voce quebrar. Apenas o
runner CDP e suportado, entao definir library e erro. Opcoes de inicializacao
nao se aplicam, entao enviar keep_alive, recording ou
lab junto com browser e erro. E nenhuma sessao reutilizavel e
criada: a resposta nao tem cabecalhos de sessao e nao pode ser continuada com
/script/<sessionId>. O Kitesurf tambem segue sua propria tabela de precos
e, hoje, esta gratis em beta.
O Kitesurf tambem nao e a opcao para sessoes autenticadas. Ele nao negocia um handshake de desafio de bot com impressoes digitais de TLS reais, e nao foi feito para sessoes autenticadas de longa duracao que precisam de estado persistente. Para entrar em uma conta e capturar o que esta atras do login, use o navegador Chromium padrao.
Rodar varios scripts ao mesmo tempo em uma mesma sessao
Requisicoes para a mesma sessao e o mesmo target nao sao serializadas. Duas execucoes
sobrepostas na mesma pagina atrapalham uma a outra - uma navega enquanto a outra le. Para
rodar em paralelo dentro de uma sessao, de a cada execucao seu proprio target: crie uma
pagina extra com a API de criacao de targets do DevTools Browser e passe esse target ID
como targetId para /script/<sessionId>. Paginas criadas
dessa forma vivem no contexto padrao da sessao, entao persistem entre execucoes e podem ser
miradas de novo depois.
Um detalhe relacionado: /script sempre fixa a execucao na primeira pagina
da sessao e devolve esse target no cabecalho cf-browser-target-id. Em
/script/<sessionId> nao existe fallback para outra pagina quando o
target que voce nomeou nao esta aberto. Um 404 ali normalmente significa que seu target ID
esta velho, e nao que a sessao morreu.
Onde isso entra em um fluxo de conteudo social
Para quem arquiva conteudo social, o appeal do /script e especifico: ele
tira o passo de implantacao entre "quero esta pagina" e "tenho esta pagina". As Quick
Actions ja davam /content, /markdown, /screenshot e
/scrape em uma requisicao cada, e o endpoint /snapshot adicionou
varios formatos em um unico carregamento de pagina. O que o /script acrescenta
e o caso de multiplos passos - entrar na conta, expandir as respostas, clicar na citacao,
esperar as imagens lazy, e so entao extrair - em uma requisicao em vez de uma cadeia delas,
sem escrever um Worker.
A ressalva honesta e que o endpoint e um navegador, e um navegador e identificavel. A
propria documentacao da Cloudflare diz que as requisicoes do Browser Run sempre serao
identificadas como bot e que um userAgent customizado nao muda isso. Sites que
bloqueiam trafego de datacenter continuam bloqueando voce. Essa e a mesma restricao de
qualquer captura headless, e e a razao pela qual um arquivo que voce tem vale mais do que
uma captura que voce aluga.
# 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
Entao o fluxo pratico e este: use o /script para obter o conteudo renderizado
que voce nao conseguiria de outro jeito, feche a sessao explicitamente e anote o horario da
captura e a URL de origem ao lado do que voce salvou. O conteudo e o ativo. A sessao de
navegador e a ferramenta que o trouxe, e ela e cobrada ate voce dizer que pode parar.
FAQ
Preciso implantar um Worker para usar o endpoint /script?
Nao. O Browser Run executa a funcao enviada em um Worker isolado conectado a sessao do navegador, entao nao ha nada para implantar antes da execucao. Voce tambem pode chamar env.BROWSER.script() de um Worker que voce ja tem, sem token de API, ou testar scripts na pagina Script Studio do painel da Cloudflare.
O endpoint /script fecha a sessao do navegador automaticamente?
Nao. Nenhum dos dois endpoints fecha a sessao depois que o seu script comecou - nem no sucesso, nem em erro, nem em timeout. A sessao continua rodando e continua contando para as suas horas de navegador ate voce fecha-la com um DELETE no endpoint devtools browser ou chamar browser.close(), ou ate o timeout de ociosidade keep_alive expirar (60 segundos por padrao, ate 20 minutos).
Qual a diferenca entre um erro 408 e um erro 422?
Um 408 significa que o seu proprio timeout era menor que o padrao da biblioteca, entao o limite de execucao interrompeu a chamada lenta. Um 422 significa que o timeout da biblioteca disparou primeiro - geralmente os 30 segundos padrao do page.goto() - e o seu script lancou excecao. Aumente o timeout da biblioteca dentro do script e mantenha-o abaixo do seu timeout para obter o comportamento que voce espera.
Quanto custa um script personalizado?
As horas de navegador sao compartilhadas por todos os metodos do Browser Run. O Workers Free inclui 10 minutos por dia; o Workers Paid inclui 10 horas por mes e depois cobra US$ 0,09 por hora adicional. Os navegadores concorrentes sao cobrados separadamente, e repare que voce paga pelo tempo de vida da sessao e nao por requisicao, entao uma sessao nao fechada continua custando dinheiro ate expirar por ociosidade.
Posso rodar scripts personalizados localmente durante o desenvolvimento?
Nao. O metodo script() nao e suportado no modo de desenvolvimento local. Use npx wrangler dev --remote, ou defina remote como true na configuracao do binding do navegador. Isso difere das Quick Actions, que funcionam localmente contra uma instancia do Chrome na sua propria maquina.
O Kitesurf e o mesmo que o navegador padrao?
Nao. Kitesurf e o navegador sem estado da Cloudflare para agentes de IA, e segue regras diferentes: apenas o runner CDP e suportado, opcoes de inicializacao nao se aplicam e nenhuma sessao reutilizavel e criada, entao uma execucao no Kitesurf nao pode ser continuada. Ele tambem nao negocia um handshake de desafio de bot com impressoes digitais de TLS reais, o que o descarta para sessoes autenticadas de longa duracao.
Um user agent customizado impede os sites de bloquearem o Browser Run?
Nao. A Cloudflare afirma que as requisicoes do Browser Run sempre serao identificadas como bot e que o user agent configuravel nao contorna a protecao contra bots. Servidores de destino que queiram bloquear o Browser Run consegue identifica-lo, entao a captura headless continua sendo uma abordagem limitada em sites que bloqueiam trafego de datacenter.
O que levar em conta
O endpoint /script da Cloudflare e uma mudanca real para quem precisa de
trabalho de navegador em multiplos passos sem rodar infraestrutura: seu codigo Playwright
ou Puppeteer sai como uma requisicao HTTP e volta como JSON. Tres coisas valem internalizar
antes de depender dele.
Primeiro, a sessao e sua. Ela nunca se fecha sozinha, continua custando ate expirar por ociosidade, e fechar e uma chamada separada. Segundo, o timeout que voce define e o timeout da sua biblioteca sao numeros diferentes que falham com codigos de status diferentes. Terceiro, a cota de concorrencia esta documentada em dois lugares que discordam - use a pagina de precos, porque e a mais nova e porque ela explica como a media e calculada.
E guarde a sua propria copia do que capturou. Uma sessao de navegador e tempo alugado na infraestrutura da Cloudflare; o arquivo e a parte que continua sendo sua.
Arquive a pagina renderizada, nao apenas a URL
O ThreadGrab salva threads publicas do X, posts do Bluesky e artigos do LinkedIn como Markdown e JSON limpos, com o horario da captura anexado. Uma sessao de navegador pode buscar a pagina renderizada; o arquivo e o que ainda e seu depois disso.
Testar o ThreadGrab →Fontes primarias
- Cloudflare Changelog — Run custom scripts in Browser Run with /script, 20 de nov 2026
- Cloudflare Docs — Custom scripts: endpoints, argumentos do runner, valores de retorno, tabelas de erro e timeout, ciclo de vida da sessao
- Cloudflare Docs — Limits: tabelas Workers Free e Workers Paid, concorrencia e keep_alive, modificado em 14 de out 2026
- Cloudflare Docs — Pricing: horas de navegador, tarifa de navegadores concorrentes, X-Browser-Ms-Used, modificado em 20 de nov 2026
- Cloudflare Docs — Get started: escolha entre Quick Actions, Browser Sessions e Custom scripts
- Cloudflare Docs — Kitesurf: navegador sem estado, apenas CDP, restricoes e o que ele nao faz
- Cloudflare Docs — Markdown endpoint: user agent customizado nao contorna a protecao contra bots
- Cloudflare Blog — Kitesurf, o navegador sem estado para agentes de IA