Node - Firecrawl Docs

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 firecrawlimport { 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.

Note

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 siteconst scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {  formats: ['markdown', 'html'],});console.log(scrapeResponse)// Fazer crawling de um siteconst 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);

Executando um agente#

Atribua uma tarefa de pesquisa ou extração a um agente usando o método agent. Forneça um prompt, um schema opcional para definir o formato do resultado e maxCredits para limitar o gasto da execução.

Node

import { Firecrawl } from 'firecrawl';import { z } from 'zod';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });const result = await firecrawl.agent({  prompt: "Find the founders of Firecrawl",  schema: z.object({    founders: z.array(z.object({      name: z.string().describe("Full name of the founder"),      role: z.string().describe("Role or position").optional(),      background: z.string().describe("Professional background").optional()    })).describe("List of founders")  }),  model: "spark-2",  maxCredits: 100});console.log(result.data);

As execuções de agentes são assíncronas. Use startAgent para receber imediatamente um ID do job e depois consulte-o com getAgentStatus.

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });// Iniciar uma tarefa do agenteconst started = await firecrawl.startAgent({  prompt: "Find the founders of Firecrawl"});// Verificar o statusif (started.id) {  const status = await firecrawl.getAgentStatus(started.id);  console.log(status.status, status.data);}

Cada execução também registra um rastro de execução e snapshots do resultado, que você pode consultar com getAgentTrace e getAgentSnapshot. Consulte Agent para ver o schema de eventos e a lista completa de parâmetros.

Rastreamento de um site com WebSockets#

Receba os resultados do rastreamento em tempo real com watcher(jobId, options). 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 acompanheconst { 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ãoconsole.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 ativasconst { sessions } = await firecrawl.listBrowsers({ status: "active" });for (const s of sessions) {  console.log(s.id, s.status, s.createdAt);}// Encerrar uma sessãoawait 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.