- 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.
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)
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.
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
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
- Use
maxAge: 0na recuperação final para que a resposta não seja servida do cache. - Não considere HTTP 200 ou conteúdo não vazio como prova de atividade.
- 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. - 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.
- Trate evidências inconclusivas como
unknowne 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
unknown.
Recomendações por cenário
Principais conclusões
-
Atualidade e disponibilidade são questões distintas.
maxAgecontrola a atualidade; a disponibilidade é uma decisão que você toma com base em evidências. - Um HTTP 200 com conteúdo não comprova que o estado representado é atual.
-
Para ações sensíveis à atualidade, use
maxAge: 0e siga a lista de verificação. Inspecione o conteúdo renderizado, comparemetadata.urlcommetadata.sourceURLem busca de possíveis evidências de redirecionamento e prefira APIs específicas da fonte. -
Trate evidências inconclusivas como
unknown. Um scraping, por si só, nunca deve classificar um objeto comoactive; interrompa antes de etapas caras ou irreversíveis. - O Firecrawl não tem um campo de disponibilidade. Sua aplicação faz essa determinação nos termos do próprio domínio.

