Sessões

Abra uma

curl -X POST https://api.scrapa.app/v1/sessions \
  -H "authorization: Bearer sc_live_your_key" \
  -H "content-type: application/json" \
  -d '{"timeoutMin": 20}'

{"data":{"id":"c0a8f2e1-5b74-4a3d-9e21-7d6f0b3c9a44","status":"live",
         "connectUrl":"wss://api.scrapa.app/v1/sessions/c0a8f2e1-…/cdp?token=…",
         "pool":"residential","timeoutMin":20,"expiresAt":"2026-01-01T12:20:00Z",
         "creditsReserved":40,"bytes":0},
 "meta":{"cost":40,"creditsRemaining":960,"requestId":"0f3c…"}}

A resposta traz o connectUrl, o socket que o seu cliente CDP conecta, já com o token da sessão dentro. Ele aparece uma única vez e não dá para remontar a partir do id, então guarde enquanto precisar do navegador.

Playwright

import { Scrapa } from "@scrapa/sdk";
import { chromium } from "playwright";

const scrapa = new Scrapa(process.env.SCRAPA_API_KEY!);
const session = await scrapa.sessions.create({ timeoutMin: 20 });

const browser = await chromium.connectOverCDP(session.connectUrl);
try {
  const page = await browser.newPage();
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await browser.close();                          // disconnects you
  await scrapa.sessions.close({ id: session.id }); // ends it, hands the rest back
}

Tudo o que você já faz com um navegador local continua valendo: contextos, páginas, cookies, o seu próprio roteamento de requisições. O único comando que reescrevemos é o que pediria outra saída. Um contexto que você criar mantém o proxy da sessão, peça o que pedir.

Puppeteer

import puppeteer from "puppeteer-core";

const session = await scrapa.sessions.create({ timeoutMin: 20 });
const browser = await puppeteer.connect({ browserWSEndpoint: session.connectUrl });

const page = await browser.newPage();
await page.goto("https://example.com");

await browser.disconnect();
await scrapa.sessions.close({ id: session.id });

Desconectar não é fechar

browser.close() no Playwright e browser.disconnect() no Puppeteer encerram a sua conexão, não a sessão. O navegador continua de pé, e continua reservado, até você fechar a sessão ou o período dela acabar.

Isso é de propósito: um script pode cair, reconectar e achar as páginas onde parou. Também quer dizer que uma sessão que ninguém fecha cobra o período inteiro que pediu. É o erro que vale um finally.

Quanto custa

curl -X POST https://api.scrapa.app/v1/sessions/quote \
  -H "authorization: Bearer sc_live_your_key" \
  -H "content-type: application/json" \
  -d '{"timeoutMin": 20}'

{"data":{"pool":"residential","timeoutMin":20,"perMinute":2,
         "maxCost":40,"freeMb":1,"perMb":10}}

Dois créditos por minuto, reservados por inteiro quando a sessão abre e acertados pelos minutos que você realmente segurou quando ela fecha. Um período de vinte minutos que você encerra em três minutos custa seis créditos. Um navegador que nunca subiu não custa nada. A banda do pool gerenciado entra no fechamento, com o primeiro megabyte incluso; o seu próprio proxy nunca é medido.

Por onde ela sai

O pool que você escolhe ao abrir a sessão é por onde sai cada byte dela, a vida inteira: páginas, subrecursos, XHR, downloads. Não dá para trocar de dentro do navegador: o único comando CDP que poderia pedir outro proxy tem esse argumento removido, e uma página que tentar passar por fora do proxy não chega a lugar nenhum. Use o seu com o pool custom, de graça em qualquer plano. O relógio e os idiomas do navegador acompanham o país de saída que você escolheu (`us` se não escolher), então a página vê um lugar só.

Quanto tempo ela dura

timeoutMin é o período, e o seu plano define o teto dele junto com quantas sessões você pode segurar ao mesmo tempo. Quando ele acaba o navegador é encerrado e a sessão se acerta sozinha. Você não precisa estar conectado para isso, e nunca paga mais do que reservou.

A sessão sobrevive aos nossos deploys. O socket CDP vai direto para o navegador, não pela API, então subir uma versão não derruba uma conexão no meio do caminho.