Monitoramento em escala de toda a web

O monitoramento em escala de toda a web é uma busca contínua que acompanha a web e avisa você ou seu agente no momento em que algo entra no ar.

Monitores de página e de site acompanham as URLs que você define. Um monitor em escala da web acompanha a web inteira. Em vez de fazer diff de páginas que você já conhece, você fornece queries e uma goal, e o Firecrawl executa as queries em cada verificação e alerta sobre resultados novos que o judge considera relevantes para esse objetivo. É descoberta, não diffing.

Cada verificação segue o mesmo ciclo: pega a meta e suas queries, aplica uma janela de recência, executa a busca, remove duplicatas dos resultados pela URL canônica, deixa o judge de IA opcional decidir quais novos resultados são significativos para a meta e envia alertas pelos mesmos canais de webhook e email usados pelos monitores de scraping e de rastreamento. Agendamento, metas, julgamento e notificações funcionam exatamente como descrito na visão geral de monitoramento.

Um alvo de busca usa type: "search" e substitui urls pelas consultas a serem executadas e por como pontuar os resultados:

{
  "type": "search",
  "queries": ["open source AI coding assistant launch"],
  "searchWindow": "24h",
  "maxResults": 10,
  "includeDomains": ["news.ycombinator.com"]
}

Um monitor em escala da web é criado da mesma forma que um monitor de página. As únicas diferenças são o target (type: "search" com queries, searchWindow, maxResults e filtros de domínio opcionais) e o fato de não haver URLs:

from firecrawl import Firecrawl

firecrawl = Firecrawl(
  # Monitor endpoints require an API key:
  api_key="fc-YOUR-API-KEY",
)

monitor = firecrawl.create_monitor(
    name="AI coding assistant launches",
    schedule={"text": "every 30 minutes", "timezone": "UTC"},
    goal="Alert when a new open-source AI coding assistant is announced. Ignore funding rounds and unrelated AI news.",
    targets=[
        {
            "type": "search",
            "queries": ["open source AI coding assistant launch"],
            "searchWindow": "24h",
            "maxResults": 10,
        }
    ],
    notification={
        "email": {
            "enabled": True,
            "recipients": ["[email protected]"],
            "includeDiffs": True,
        }
    },
)

print(monitor.id)

Quando um novo resultado correspondente é encontrado, o webhook monitor.page o reporta com status new e, quando o julgamento é executado, com um judgment descrevendo por que ele é importante:

{
  "success": true,
  "type": "monitor.page",
  "id": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
  "webhookId": "f1e2d3c4-0000-0000-0000-000000000000",
  "data": [
    {
      "monitorId": "019df960-06e7-7383-9d89-82c0113dc31a",
      "checkId": "019df960-5f2a-75fb-a98b-bd2d32ca67d4",
      "url": "https://news.ycombinator.com/item?id=40000000",
      "status": "new",
      "error": null,
      "isMeaningful": true,
      "judgment": {
        "meaningful": true,
        "confidence": "high",
        "reason": "A new open-source AI coding assistant was announced, which matches the monitor goal."
      }
    }
  ],
  "metadata": {
    "environment": "production"
  }
}

A qualidade de um monitor em escala da web depende de dois fatores que cumprem papéis diferentes:

• queries controlam o recall: o que cada busca traz. Se forem específicas demais, eventos reais nunca aparecem; se forem amplas demais, o judge gasta credits filtrando ruído.
• meta controla a precisão: quais resultados recuperados realmente geram alert. O judge avalia cada novo resultado em relação à meta, então é a meta que separa uma correspondência real de algo relacionado ao tema, mas irrelevante na prática.

Ajuste os dois. Uma meta perfeita não pode gerar alert para um resultado que as queries nunca recuperaram, e queries amplas combinadas com uma meta vaga produzem alertas constantes de baixo valor.

Boas queries se parecem com termos de busca, não com frases:

• Use palavras-chave, não texto corrido: OpenAI new model release, não tell me when OpenAI releases a new model.
• Coloque entre aspas entidades com várias palavras ("Llama 4") e agrupe sinônimos com OR (launch OR release OR announcement).
• Mantenha cada query enxuta (cerca de 2 a 6 termos). Uma query ampla geralmente supera várias queries restritas, porque queries extras dividem o orçamento de maxResults sem aumentar a cobertura.
• Use uma query por assunto distinto. Um único assunto com várias facetas (“launches, benchmarks, docs”) continua sendo uma query; só divida quando a meta realmente citar entidades separadas (por exemplo, “OpenAI, Anthropic, and Google”).
• Não use operadores site: / -site: nas queries. Use includeDomains / excludeDomains no lugar.

Boas metas descrevem a correspondência em linguagem simples e adicionam exclusões apenas quando fazem parte da intenção:

• Nomeie o assunto e o que conta como correspondência: “Alert when OpenAI announces a brand-new model.”
• Esclareça termos ambíguos: “Firecrawl (the web scraping API)” evita que o judge confunda com equipamentos de combate a incêndio.
• Adicione Ignore ... apenas para não correspondências específicas da intenção: “Ignore opinion pieces, tutorials, and unrelated AI news.” Não repita ruído genérico. O judge já lida com formatação, parâmetros de rastreamento e mudanças de reindexação.
• Se a intenção for ampla, mantenha-a ampla. Metas específicas demais suprimem correspondências reais.

Como é um monitor saudável. Um monitor em escala da web bem ajustado, na maior parte do tempo, não reporta nada. A maioria das verificações retorna new: 0, e os alertas só disparam quando algo realmente novo e alinhado à meta aparece. Leia o resumo da verificação e o searchStatus de cada resultado (veja Statuses and dedup) para saber se ele está bem ajustado:

• Um fluxo constante de resultados ignored significa que as queries trazem ruído, que a meta depois rejeita. Restrinja as queries (ou reduza searchWindow) para parar de pagar para o judge avaliar resultados que nunca vão gerar alert.
• watching frequente significa que a meta está ambígua. Deixe os critérios de correspondência mais claros para que o judge possa decidir.
• Longos períodos sem resultados em um tema ativo significam que as queries são restritas demais ou que searchWindow está estreita demais. Amplie os termos ou aumente a janela.
• Alertas que o usuário dispensa significam que a meta está ampla demais. Adicione um Ignore ... específico para a intenção.

O resultado ideal é alta precisão com recall suficiente: todo alerta vale a pena ser tratado, e nada importante é perdido.

A quantidade de trabalho que cada verificação faz por resultado é controlada pelo judgeEnabled do monitor, a mesma flag descrita em Metas e julgamento. Com o julgamento ativado, o Firecrawl faz scraping de cada resultado correspondente e avalia seu conteúdo em relação à meta, cobrando 1 crédito por resultado avaliado além da chamada de busca. Com judgeEnabled: false, um monitor em escala da web retorna os resultados de busca deduplicados sem julgamento por IA, apenas os novos resultados na SERP, e consome apenas os créditos das chamadas de busca (2 créditos por 10 resultados).

Os resultados de busca usam o mesmo enum status por página que os monitores de scraping e rastreamento, então os consumidores existentes de webhooks e resultados de verificação continuam funcionando sem alterações. Um resultado de busca é mapeado para:

• new: um resultado que correspondeu à meta pela primeira vez. É isso que gera alertas.
• same: um resultado já visto em uma verificação anterior (sem novo alerta).
• error: um resultado que não pôde ser avaliado (por exemplo, o scraping para julgamento foi pulado).

O status de busca mais detalhado é exposto em metadata.searchStatus de cada página, com um destes valores:

Um resultado gera alerta uma vez, quando aparece pela primeira vez como new. A deduplicação é baseada apenas na URL canônica (título e snippet deliberadamente não fazem parte do fingerprint, então uma mudança de título/snippet não dispara de novo). Como a chave é a URL, um evento do mundo real reportado em várias URLs de artigos gera um alerta por URL, não um por evento.

Editar a meta ou as queries do monitor incrementa seu goalVersion, o que invalida vereditos anteriores do judge. A reavaliação é feita sob demanda, e não em massa: os resultados existentes não são todos reavaliados de uma vez. Em vez disso, cada resultado é reavaliado na próxima vez em que reaparece em uma verificação, adotando então o novo goalVersion. Resultados que não reaparecem mantêm seu veredito antigo e o goalVersion anterior até reaparecerem.

• Agendamentos: cron ou frequência em linguagem natural, no mínimo 5 minutos.
• Metas e julgamento: obrigatório para alvos de busca, a menos que judgeEnabled: false.
• Notificações: envio via webhook e email.
• Resultados das verificações: inspecione cada verificação e seus resultados.
• Preços: 2 créditos a cada 10 resultados por verificação, mais 1 crédito por resultado avaliado.