Node SDK | Firecrawl

Faça scraping de páginas individuais, rastreie sites inteiros e mapeie URLs no seu aplicativo Node.js. O SDK gerencia a paginação, as novas tentativas e a consulta assíncrona de jobs para que você possa se concentrar nos dados retornados.

Instalação

Instale o SDK com npm:

Node

// npm install firecrawl

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({
  // Nenhuma API key necessária para começar — adicione uma para limites de taxa maiores:
  // apiKey: "fc-YOUR-API-KEY",
});

Uso

Obtenha uma chave de API em firecrawl.dev
Defina a chave de API como uma variável de ambiente chamada FIRECRAWL_API_KEY ou passe-a como parâmetro para a classe Firecrawl.

Sem chave de API? Você pode instanciar Firecrawl sem uma chave e usar scrape, search e interact no plano gratuito sem chave (com limite de taxa por IP — veja Limites de taxa). Todos os outros métodos exigem uma chave.

Veja um exemplo de como usar o SDK com tratamento de erros:

Node

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

// Fazer scraping de um site
const scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

// Fazer crawling de um site
const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
});

console.log(crawlResponse)

Scraping de uma URL

Use o método scrape para extrair os dados de uma única URL e receber os dados estruturados da página.

Node

// Fazer scraping de um site:
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

Análise de arquivos enviados

Use parse quando quiser enviar um arquivo local (html, pdf, docx, xlsx, etc.) em vez de fazer scraping a partir de uma URL. parse não oferece suporte a changeTracking nem a opções exclusivas do navegador, como screenshot, branding, actions, waitFor, location e mobile.

Node

const parsed = await firecrawl.parse(
  {
    data: "<html><body><h1>Node Parse</h1></body></html>",
    filename: "upload.html",
    contentType: "text/html",
  },
  {
    formats: ["markdown"],
  },
);

console.log(parsed.markdown);

Rastreando um site

Rastreie um site inteiro a partir de uma única URL com o método crawl. Você pode definir um limite de páginas, restringir o rastreamento a domínios específicos e escolher formatos de resultado. Consulte Paginação para paginação automática e manual.

Node

const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);

Rastreamento Somente do Sitemap

Use sitemap: "only" para rastrear apenas URLs do sitemap (a URL inicial sempre é incluída e a descoberta de links em HTML é ignorada).

Node

const job = await firecrawl.crawl('https://docs.firecrawl.dev', {
  sitemap: 'only',
  limit: 25,
});
console.log(job.status, job.data.length);

Iniciar um rastreamento

Inicie um rastreamento sem aguardar a conclusão usando startCrawl. O método retorna um ID do job que você pode consultar depois. Use crawl em vez disso quando quiser bloquear até a conclusão. Veja Paginação para comportamento e limites de paginação.

Node

const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);

Verificando o status do rastreamento

Verifique se um rastreamento ainda está em execução, foi concluído ou falhou usando o método checkCrawlStatus. Passe o ID do job retornado por startCrawl.

Node

const status = await firecrawl.getCrawlStatus("<id-da-varredura>");
console.log(status);

Cancelando um rastreamento

Cancele um rastreamento em andamento usando o método cancelCrawl. Informe o ID do job retornado por startCrawl.

Node.js

const ok = await firecrawl.cancelCrawl("<crawl-id>");
console.log("Cancelado:", ok);

Mapeando um site

Descubra todas as URLs de um site com o método map. Informe uma URL inicial e receba uma lista das páginas encontradas.

Node.js

const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });
console.log(res.links);

Rastreamento de um site com WebSockets

Receba os resultados do rastreamento em tempo real com o método crawlUrlAndWatch. Você recebe cada página conforme ela é rastreada, em vez de aguardar a conclusão de todo o job.

Node

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// Inicie um crawl e depois acompanhe
const { id } = await firecrawl.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

watcher.on('document', (doc) => {
  console.log('DOC', doc);
});

watcher.on('error', (err) => {
  console.error('ERR', err?.error || err);
});

watcher.on('done', (state) => {
  console.log('DONE', state.status);
});

// Comece a acompanhar (WS com fallback em HTTP)
await watcher.start();

Paginação

Os endpoints do Firecrawl para crawl e batch retornam uma URL next quando há mais dados disponíveis. O SDK de Node faz paginação automática por padrão e agrega todos os documentos; nesse caso, next será null. Você pode desativar a paginação automática ou definir limites.

Rastreamento

Use o método waiter crawl para a experiência mais simples, ou inicie um job e faça a paginação manualmente.

Rastreamento simples (paginação automática, padrão)

Veja o fluxo padrão em Rastrear um site.

Rastreamento manual com controle de paginação (página única)

Inicie um job e, em seguida, recupere uma página por vez com autoPaginate: false.

Node

const crawlStart = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 5 });
const crawlJobId = crawlStart.id;

const crawlSingle = await firecrawl.getCrawlStatus(crawlJobId, { autoPaginate: false });
console.log('rastreamento de página única:', crawlSingle.status, 'docs:', crawlSingle.data.length, 'próximo:', crawlSingle.next);

Rastreamento manual com limites (paginação automática + parada antecipada)

Mantenha a paginação automática ativada, mas interrompa antecipadamente com maxPages, maxResults ou maxWaitTime.

Node

const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('crawl limitado:', crawlLimited.status, 'docs:', crawlLimited.data.length, 'próximo:', crawlLimited.next);

Coleta em lote

Use o método waiter batchScrape ou inicie uma tarefa e pagine manualmente.

Raspagem em lote simples (paginação automática, padrão)

Veja o fluxo padrão em Raspagem em lote.

Coleta manual em lote com controle de paginação (página única)

Inicie um job e, em seguida, recupere uma página por vez com autoPaginate: false.

Node

const batchStart = await firecrawl.startBatchScrape([
  'https://docs.firecrawl.dev',
  'https://firecrawl.dev',
], { options: { formats: ['markdown'] } });
const batchJobId = batchStart.id;

const batchSingle = await firecrawl.getBatchScrapeStatus(batchJobId, { autoPaginate: false });
console.log('página única do lote:', batchSingle.status, 'docs:', batchSingle.data.length, 'próximo:', batchSingle.next);

Coleta manual em lote com limites (paginação automática + parada antecipada)

Mantenha a paginação automática ligada, mas interrompa antes com maxPages, maxResults ou maxWaitTime.

Node

const batchLimited = await firecrawl.getBatchScrapeStatus(batchJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 100,
  maxWaitTime: 20,
});
console.log('lote limitado:', batchLimited.status, 'docs:', batchLimited.data.length, 'próximo:', batchLimited.next);

Browser

Inicie sessões de navegador na nuvem e execute código remotamente.

Criar sessão

Node

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const session = await firecrawl.browser({ ttl: 600 });
console.log(session.id);          // ID da sessão
console.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

Executar código

Node

const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
});
console.log(result.result); // "Hacker News"

Use JavaScript em vez de Python:

Node

const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://example.com"); const t = await page.title(); console.log(t);',
  language: "node",
});

Execute o bash usando agent-browser:

Node

const result = await firecrawl.browserExecute(session.id, {
  code: "agent-browser open https://example.com && agent-browser snapshot",
  language: "bash",
});

Perfis

Salve e reutilize o estado do navegador (cookies, localStorage etc.) entre sessões:

Node

const session = await firecrawl.browser({
  ttl: 600,
  profile: {
    name: "my-profile",
    saveChanges: true,
  },
});

Conectar via CDP

Para controle completo do Playwright, conecte-se diretamente usando a URL do CDP:

Node

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();

Listar & Encerrar Sessões

Node

// Listar sessões ativas
const { sessions } = await firecrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
  console.log(s.id, s.status, s.createdAt);
}

// Encerrar uma sessão
await firecrawl.deleteBrowser(session.id);

Sessão interativa vinculada ao scraping

Use o ID de um job de scraping para continuar interagindo com o contexto da página recriado a partir desse scraping:

interact(jobId, {...}) executa código na sessão do navegador vinculada ao scraping.
A primeira chamada de interact inicializa automaticamente a sessão com base no contexto do scraping.
Chamadas adicionais de interact com o mesmo ID do job reutilizam esse estado ativo do navegador.
stopInteraction(jobId) encerra a sessão interativa quando você terminar.

Node

const doc = await firecrawl.scrape("https://example.com", {
  actions: [{ type: "click", selector: "a[href='/pricing']" }],
});

const scrapeJobId = doc.metadata?.scrapeId;
if (!scrapeJobId) throw new Error("Missing scrape job id");

const run = await firecrawl.interact(scrapeJobId, {
  code: "console.log(await page.url())",
  language: "node",
  timeout: 60,
});
console.log(run.stdout);

await firecrawl.stopInteraction(scrapeJobId);

Tratamento de erros

O SDK lança exceções descritivas para qualquer erro retornado pela API do Firecrawl. Coloque as chamadas em blocos try/catch, como mostrado nos exemplos acima.

Você é um agente de IA que precisa de uma chave de API do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para ver instruções automatizadas de onboarding.

​Instalação

​Uso

​Scraping de uma URL

​Análise de arquivos enviados

​Rastreando um site

​Rastreamento Somente do Sitemap

​Iniciar um rastreamento

​Verificando o status do rastreamento

​Cancelando um rastreamento

​Mapeando um site

​Rastreamento de um site com WebSockets

​Paginação

​Rastreamento

Rastreamento simples (paginação automática, padrão)

Rastreamento manual com controle de paginação (página única)

Rastreamento manual com limites (paginação automática + parada antecipada)

​Coleta em lote

Raspagem em lote simples (paginação automática, padrão)

Coleta manual em lote com controle de paginação (página única)

Coleta manual em lote com limites (paginação automática + parada antecipada)

​Browser

​Criar sessão

​Executar código

​Perfis

​Conectar via CDP

​Listar & Encerrar Sessões

​Sessão interativa vinculada ao scraping

​Tratamento de erros

Instalação

Uso

Scraping de uma URL

Análise de arquivos enviados

Rastreando um site

Rastreamento Somente do Sitemap

Iniciar um rastreamento

Verificando o status do rastreamento

Cancelando um rastreamento

Mapeando um site

Rastreamento de um site com WebSockets

Paginação

Rastreamento

Coleta em lote

Browser

Criar sessão

Executar código

Perfis

Conectar via CDP

Listar & Encerrar Sessões

Sessão interativa vinculada ao scraping

Tratamento de erros