Pular para o conteúdo principal
Referência para todas as opções em todos os endpoints de scraping, rastreamento, mapeamento e agente do Firecrawl.”

scraping básica

Para raspar uma única página e obter conteúdo em Markdown limpo, use o endpoint /scrape.

Extração de PDFs

O Firecrawl oferece suporte a PDFs. Use a opção parsers (por exemplo, parsers: ["pdf"]) quando quiser garantir a extração de PDFs. Você pode controlar a estratégia de extração com a opção mode:
  • auto (padrão) — tenta primeiro uma extração rápida baseada em texto e, se necessário, recorre a OCR.
  • fast — apenas extração baseada em texto (texto embutido). Mais rápido, mas ignora páginas digitalizadas ou com muitas imagens.
  • ocr — força a extração via OCR em todas as páginas. Use para documentos digitalizados ou quando auto classificar uma página incorretamente.
{ type: "pdf" } e "pdf" usam por padrão mode: "auto".

Opções de scraping

Ao usar o endpoint /scrape, você pode personalizar a requisição com as seguintes opções.

Formatos (formats)

O array formats controla quais tipos de saída o scraper retorna. Padrão: ["markdown"]. Formatos em string: passe o nome diretamente (por exemplo, "markdown"). Formatos em objeto: passe um objeto com type e opções adicionais.

Scraping móvel

Defina mobile: true para emular um dispositivo móvel. Isso é útil quando um site responsivo oculta conteúdo na versão desktop ou exibe um layout diferente em navegadores móveis. Para sites específicos de uma região, combine com location e uma captura de tela em um dispositivo móvel para verificar o layout renderizado:
Se o site ainda exibir um layout para desktop apesar de mobile: true, adicione um User-Agent mobile via headers:

Filtragem de conteúdo

Esses parâmetros controlam quais partes da página aparecem na saída. Quando onlyMainContent é true (o padrão), o boilerplate (nav, footer etc.) é removido. includeTags e excludeTags são aplicados ao DOM original da página, não ao resultado após a filtragem, portanto seus seletores devem segmentar os elementos conforme aparecem no HTML de origem. Defina onlyMainContent: false para usar a página completa como ponto de partida para a filtragem por tags.

Tempo e cache

Análise de PDF

Ações

Execute ações no navegador antes do scraping. Isso é útil para conteúdo dinâmico, navegação ou páginas com acesso restrito. Você pode incluir até 50 ações por requisição, e o tempo total de espera entre todas as ações wait e waitFor não pode exceder 60 segundos.

Observações sobre a execução de ações

  • Write requer um click anterior para focar o elemento de destino.
  • Scroll aceita um selector opcional para rolar um elemento específico em vez da página.
  • Wait aceita milliseconds (atraso fixo) ou selector (esperar até que fique visível).
  • As ações são executadas sequencialmente: cada etapa é concluída antes da próxima começar.
  • Ações não são compatíveis com PDFs. Se a URL for resolvida para um PDF, a requisição falhará.

Exemplos de Ações Avançadas

Fazendo uma captura de tela:
cURL
Clicar em vários elementos:
cURL
Gerar um PDF:
cURL
Executar JavaScript (por exemplo, para extrair dados embutidos na página):
cURL
O valor de retorno de cada ação executeJavascript é armazenado no array actions.javascriptReturns da resposta.

Exemplo completo de scraping

A solicitação abaixo combina várias opções de scraping:
cURL
Essa requisição retorna markdown, HTML, HTML bruto, links e uma captura de tela da página inteira. Ela restringe o conteúdo a <h1>, <p>, <a> e .main-content, enquanto exclui #ad e #footer, aguarda 1 segundo antes de iniciar o scraping, define um tempo limite de 15 segundos e habilita a análise de PDFs. Consulte a referência completa da API de Scrape para mais detalhes.

Extração em JSON via formatos

Use o objeto de formato JSON em formats para extrair dados estruturados de uma só vez:

Endpoint do agente

Use o endpoint /v2/agent para extração autônoma de dados em várias páginas. O agente é executado de forma assíncrona: você inicia uma tarefa e depois faz polling dos resultados.

Opções do agente

Verificar status do agente

Faça requisições periódicas para GET /v2/agent/{jobId} para verificar o progresso. O campo status da resposta será "processing", "completed" ou "failed".
cURL
Os SDKs de Python e Node também fornecem um método conveniente (firecrawl.agent()) que inicia o job e consulta o status automaticamente até a conclusão.

Rastreamento de várias páginas

Para rastrear várias páginas, use o endpoint /v2/crawl. O rastreamento é executado de forma assíncrona e retorna um ID do job. Use o parâmetro limit para controlar quantas páginas serão rastreadas. Se omitido, o rastreamento processará até 10.000 páginas.
cURL

Resposta

Verificar o job de rastreamento

Use o ID do job para verificar o status do rastreamento e recuperar os resultados.
cURL
Se o conteúdo tiver mais de 10MB ou se o job de rastreamento ainda estiver em execução, a resposta pode incluir o parâmetro next, uma URL para a próxima página de resultados.

Prévia do prompt e dos parâmetros de rastreamento

Você pode fornecer um prompt em linguagem natural para que o Firecrawl defina as configurações de rastreamento. Visualize-as primeiro:
cURL

Opções do crawler

Ao usar o endpoint /v2/crawl, você pode configurar o comportamento do crawler com as seguintes opções.

Filtragem de caminhos

A URL inicial também é verificada em relação a includePaths. Se ela não corresponder a nenhum dos padrões, o rastreamento poderá retornar 0 páginas.

Escopo do rastreamento

Sitemap e deduplicação

Opções de scrape para crawl

Exemplo de rastreamento

cURL
O endpoint /v2/map identifica URLs relacionadas a um determinado website.
cURL

Opções do Map

Aqui está a referência da API: Documentação do endpoint Map

Adicionando o Firecrawl à lista de permissões

Como permitir que o Firecrawl faça scraping do seu site

  • User Agent: permita FirecrawlAgent no seu firewall ou nas suas regras de segurança.
  • Endereços IP: o Firecrawl não usa um conjunto fixo de IPs de saída.

Permitindo que sua aplicação faça chamadas à API do Firecrawl

Se o seu firewall bloquear requisições de saída da sua aplicação para serviços externos, você precisa adicionar o endereço IP do servidor da API do Firecrawl à lista de permissões para que sua aplicação possa acessar a API do Firecrawl (api.firecrawl.dev):
  • Endereço IP: 35.245.250.27
Adicione esse IP à lista de permissões de saída do seu firewall para que seu backend possa enviar requisições de scrape, crawl, map e agent para o Firecrawl.