Skip to main content
Um scraping bem-sucedido informa o que a página retornou. Ele não comprova que o estado representado pela página ainda é válido. Essas são duas questões distintas.
  • Atualidade → Este conteúdo é recente ou uma cópia reutilizada do cache do Firecrawl? Controlada por maxAge.
  • Disponibilidade → O item subjacente ainda existe e está ativo? Sua aplicação determina isso com base nas evidências disponíveis.
Este guia explica a diferença, aborda o trade-off de maxAge e apresenta uma checklist e um exemplo prático para ações sensíveis à atualidade.

Comparação rápida


O equilíbrio entre atualidade e desempenho (maxAge)

O Firecrawl armazena em cache páginas extraídas anteriormente e retorna uma cópia recente quando disponível, reduzindo a latência. maxAge é a idade máxima, em milissegundos, de uma cópia em cache que o Firecrawl pode retornar em vez de recuperar a página novamente.
  • Omita maxAge: o Firecrawl pode retornar conteúdo armazenado em cache recentemente. A janela padrão é de 2 dias; o Firecrawl pode usar uma janela diferente para alguns sites.
  • Defina maxAge: 0: o Firecrawl ignora o cache para essa solicitação e recupera a página. Isso troca latência e confiabilidade por uma recuperação mais atualizada.
Mantenha o cache ativado por padrão. Pague o custo de latência de maxAge: 0 apenas nas leituras em que conteúdo desatualizado poderia levar a uma decisão incorreta ou custosa — isso não altera o custo da página em créditos. metadata.cacheState é retornado quando o Firecrawl considera o cache para a solicitação, portanto é útil para verificação enquanto você ajusta maxAge. Ele não faz parte de uma resposta com maxAge: 0, porque essa solicitação ignora o cache por completo. Para detalhes sobre o funcionamento do cache, valores comuns de maxAge, regras de correspondência para acertos de cache e as opções de solicitação que ignoram o cache automaticamente, consulte Scraping mais rápido.

Onde maxAge se aplica

Se precisar obter uma versão atualizada de uma página encontrada por meio de /search, faça scraping desse URL novamente com /scrape e maxAge: 0.

Atualidade não é disponibilidade

Mesmo com maxAge: 0, o resultado informa apenas o que a página retornou naquela consulta. Uma página pode retornar HTTP 200 com conteúdo, mas ainda assim representar um estado desatualizado, indisponível ou alterado de alguma outra forma. Portanto, nem o código de status nem a presença de conteúdo determinam a disponibilidade. A disponibilidade é uma conclusão que sua aplicação tira com base em evidências específicas da fonte.

Checklist de Ações Sensíveis à Atualidade

Antes de realizar uma ação que dependa do estado atual, trate o resultado do scraping como evidência, não prova:
  1. Use maxAge: 0 na recuperação final para que a resposta não seja servida do cache.
  2. Não considere HTTP 200 ou conteúdo não vazio como prova de atividade.
  3. Inspecione o conteúdo renderizado e as evidências de redirecionamento. metadata.sourceURL é a URL solicitada; metadata.url é a URL que o mecanismo informa para a resposta. Quando elas diferem, isso pode indicar um redirecionamento para outro recurso. Valores idênticos não comprovam que não houve redirecionamento.
  4. Prefira APIs ou identificadores específicos da fonte quando disponíveis — eles geralmente expõem um status explícito que uma página renderizada oculta.
  5. Trate evidências inconclusivas como unknown e interrompa antes da etapa cara ou irreversível, em vez de presumir que está ativo.

Exemplo Prático: Coleta de Evidências da Página Atual

Ignore o cache e colete o conteúdo renderizado e os metadados da resposta para aplicar as regras de validação da sua aplicação. O scraping fornece evidências; não determina o estado específico do domínio.
O ponto-chave é o que acontece após a coleta: o Firecrawl fornece evidências da página; sua aplicação interpreta essas evidências com regras específicas da fonte. Se essas regras forem inconclusivas, mantenha o estado como unknown.

Recomendações por cenário


Principais conclusões

  1. Atualidade e disponibilidade são questões distintas. maxAge controla a atualidade; a disponibilidade é uma decisão que você toma com base em evidências.
  2. Um HTTP 200 com conteúdo não comprova que o estado representado é atual.
  3. Para ações sensíveis à atualidade, use maxAge: 0 e siga a lista de verificação. Inspecione o conteúdo renderizado, compare metadata.url com metadata.sourceURL em busca de possíveis evidências de redirecionamento e prefira APIs específicas da fonte.
  4. Trate evidências inconclusivas como unknown. Um scraping, por si só, nunca deve classificar um objeto como active; interrompa antes de etapas caras ou irreversíveis.
  5. O Firecrawl não tem um campo de disponibilidade. Sua aplicação faz essa determinação nos termos do próprio domínio.

Leitura complementar