Passer au contenu principal
La surveillance à l’échelle de l’ensemble du web est une recherche continue qui scrute le web et vous avertit, vous ou votre agent, dès que quelque chose apparaît en ligne. Les monitors de page et de site web surveillent les URL que vous indiquez. Un monitor à l’échelle de l’ensemble du web surveille l’ensemble du web. Au lieu de comparer des diff de pages que vous connaissez déjà, vous lui fournissez des queries à exécuter ainsi qu’un goal, et Firecrawl lance les requêtes à chaque check puis envoie des alertes sur les nouveaux résultats que le juge juge pertinents par rapport au goal. Il s’agit de découverte plutôt que de diff. Chaque check suit le même cycle : prendre le goal et ses queries, appliquer une fenêtre de récence, exécuter la recherche, dédupliquer les résultats par URL canonique, laisser le juge IA facultatif décider quels nouveaux résultats sont significatifs pour le goal, puis envoyer des alertes via les mêmes canaux webhook et e-mail que les monitors de scrape et de crawl. La planification, les goals, l’évaluation et les notifications fonctionnent exactement comme décrit dans la vue d’ensemble de la surveillance.
Les monitors de page et de crawl comparent les différences de contenu sur les URL que vous indiquez ; les monitors à l’échelle du web découvrent de nouveaux résultats sur l’ensemble du web. La planification, le juge et les notifications reposent sur le même fonctionnement sous-jacent.

​
Cible de recherche

Une cible de recherche utilise type: "search" et remplace urls par les requêtes à exécuter ainsi que la façon d’évaluer les résultats :
Search target
{
  "type": "search",
  "queries": ["open source AI coding assistant launch"],
  "searchWindow": "24h",
  "maxResults": 10,
  "includeDomains": ["news.ycombinator.com"]
}
ChampTypeDescription
type"search"Sélectionne la cible de recherche.
queriesstring[]Requêtes de recherche à exécuter à chaque vérification. 1 à 12 requêtes, jusqu’à 256 caractères chacune. Obligatoire.
searchWindow"5m" | "15m" | "1h" | "6h" | "24h" | "7d"Filtre de récence. Ne prendre en compte que les résultats publiés dans cet intervalle. Par défaut, 24h.
maxResultsnumberNombre total de résultats à évaluer par vérification, 1–50. Par défaut, 10. Il s’agit d’un plafond global pour toutes les queries (les résultats sont d’abord fusionnés et dédupliqués), et non d’une limite par requête. Une requête donnée peut donc fournir moins de résultats, voire aucun, si d’autres requêtes atteignent d’abord ce plafond.
includeDomainsstring[]Optionnel. Limite les résultats à ces domaines (jusqu’à 50). Ne peut pas être utilisé avec excludeDomains.
excludeDomainsstring[]Optionnel. Exclut les résultats de ces domaines (jusqu’à 50). Ne peut pas être utilisé avec includeDomains.
Une cible de recherche nécessite un goal non vide au niveau du monitor, sauf si vous définissez judgeEnabled: false. Les queries sont obligatoires ; le goal sert de référence au juge pour évaluer chaque nouveau résultat. Il ne génère pas les requêtes. Voir Objectifs et évaluation.
Les crédits augmentent avec le nombre de requêtes. Chaque requête récupère jusqu’à maxResults résultats, et les crédits des appels de recherche sont facturés sur les résultats bruts de l’ensemble des requêtes avant fusion et déduplication. Ajouter des requêtes augmente donc le coût réel de la recherche, pas seulement l’estimation initiale. Après fusion/déduplication, Firecrawl évalue au plus maxResults candidats sélectionnés, de sorte que les crédits du juge restent plafonnés par le nombre de résultats sélectionnés/évalués.

​
Créer un monitor à l’échelle du Web

Un monitor à l’échelle du Web se crée de la même manière qu’un monitor de page. Les seules différences concernent la cible (type: "search" avec queries, searchWindow, maxResults et, éventuellement, des filtres de domaine) et l’absence d’URL : 
from firecrawl import Firecrawl

firecrawl = Firecrawl(
  # Les points de terminaison de monitor nécessitent une 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": ["alerts@example.com"],
            "includeDiffs": True,
        }
    },
)

print(monitor.id)
Lorsqu’un nouveau résultat correspondant est détecté, le webhook monitor.page le signale avec l’état new et, lorsqu’une évaluation a été effectuée, un judgment expliquant pourquoi c’est important :
monitor.page
{
  "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"
  }
}

​
Rédiger de bons objectifs et de bonnes requêtes

La qualité d’un monitor à l’échelle du web repose sur deux leviers aux rôles distincts :
  • queries contrôlent le rappel : ce que chaque recherche fait remonter. Trop étroites, les vrais événements ne remontent jamais ; trop larges, et le juge dépense des crédits à filtrer le bruit.
  • goal contrôle la précision : quels résultats récupérés déclenchent réellement une alerte. Le juge évalue chaque nouveau résultat par rapport à l’objectif : c’est donc l’objectif qui distingue une vraie correspondance d’un résultat lié au sujet, mais non pertinent.
Réglez les deux. Un objectif parfait ne peut pas déclencher d’alerte sur un résultat que les requêtes n’ont jamais récupéré, et des requêtes larges associées à un objectif vague produisent des alertes permanentes de faible valeur. De bonnes requêtes ressemblent à des termes de recherche, pas à des phrases :
  • Utilisez des mots-clés, pas des phrases : OpenAI new model release, pas tell me when OpenAI releases a new model.
  • Mettez entre guillemets les entités de plusieurs mots ("Llama 4") et regroupez les synonymes avec OR (launch OR release OR announcement).
  • Gardez chaque requête concise (environ 2 à 6 termes). Une requête large est généralement préférable à plusieurs requêtes étroites, car des requêtes supplémentaires répartissent le budget maxResults sans améliorer la couverture.
  • Utilisez une requête par sujet distinct. Un même sujet avec plusieurs facettes (“launches, benchmarks, docs”) reste une seule requête ; ne scindez que lorsque l’objectif mentionne de véritables entités distinctes (par exemple, “OpenAI, Anthropic, and Google”).
  • N’utilisez pas les opérateurs site: / -site: dans les requêtes. Utilisez plutôt includeDomains / excludeDomains.
De bons objectifs décrivent clairement la correspondance attendue et n’ajoutent des exclusions que lorsqu’elles font partie de l’intention :
  • Nommez le sujet et ce qui constitue une correspondance : “Alert when OpenAI announces a brand-new model.”
  • Levez les ambiguïtés sur les termes polysémiques : “Firecrawl (the web scraping API)” évite que le juge ne parte sur du matériel de lutte contre l’incendie.
  • Ajoutez Ignore ... uniquement pour les non-correspondances propres à l’intention : “Ignore opinion pieces, tutorials, and unrelated AI news.” Ne reformulez pas le bruit générique. Le juge gère déjà la mise en forme, les paramètres de suivi et les réindexations.
  • Si l’intention est large, gardez-la large. Des objectifs trop restrictifs écartent de vraies correspondances.
À quoi ressemble un monitor sain. Un monitor à l’échelle du web bien réglé ne signale généralement rien. La plupart des checks renvoient new: 0, et les alertes ne se déclenchent que lorsqu’un élément réellement nouveau et conforme à l’objectif apparaît. Lisez le résumé du check et le searchStatus de chaque résultat (voir Statuses and dedup) pour déterminer s’il est bien réglé :
  • Un flux régulier de résultats ignored signifie que les requêtes font remonter du bruit que l’objectif rejette ensuite. Resserrez les requêtes (ou réduisez searchWindow) pour ne plus payer le jugement de résultats qui ne déclencheront jamais d’alerte.
  • Des watching fréquents signifient que l’objectif est ambigu. Affinez les critères de correspondance pour que le juge puisse trancher.
  • De longues périodes sans résultat sur un sujet actif signifient que les requêtes sont trop étroites ou que searchWindow est trop réduit. Élargissez les termes ou la fenêtre.
  • Les alertes que l’utilisateur ignore signifient que l’objectif est trop large. Ajoutez un Ignore ... propre à l’intention.
Le résultat visé est une précision élevée avec un rappel suffisant : chaque alerte mérite une action, sans rien manquer d’important.

​
Évaluation

La charge de travail de chaque vérification pour chaque résultat est contrôlée par le paramètre judgeEnabled du monitor, le même indicateur décrit dans Objectifs et évaluation. Lorsque l’évaluation est activée, Firecrawl scrape chaque résultat correspondant et évalue son content par rapport à l’objectif, avec une facturation de 1 credit par résultat évalué en plus de l’appel de recherche. Avec judgeEnabled: false, un monitor à l’échelle du web retourne les résultats de recherche dédupliqués sans aucune évaluation par IA, uniquement les nouveaux résultats du SERP, et ne consomme que les credits de l’appel de recherche (2 credits par 10 résultats).

​
États et déduplication

Les résultats de recherche utilisent la même énumération status au niveau de la page que les monitors de scrape et de crawl, afin que les consommateurs existants de webhooks et de résultats de vérification continuent de fonctionner sans modification. Un résultat de recherche correspond à :
  • new : un résultat qui a correspondu à l’objectif pour la première fois. C’est ce qui déclenche une alerte.
  • same : un résultat déjà vu lors d’une vérification précédente (aucune nouvelle alerte).
  • error : un résultat qui n’a pas pu être évalué (par exemple, si le scrape nécessaire à l’évaluation a été ignoré).
L’état de recherche plus fin est exposé dans le champ metadata.searchStatus de chaque page, avec l’une des valeurs suivantes :
searchStatusPage statusSignification
alertnewNouveau résultat que le juge considère comme pertinent — déclenche une notification.
already_seensameL’empreinte correspond à un résultat d’une vérification antérieure.
watchingsameNouveau résultat sur lequel le juge n’est pas encore suffisamment sûr ; il est suivi, mais ne déclenche pas d’alerte.
ignoredsameNouveau résultat que le juge a estimé non pertinent par rapport à l’objectif.
skippederrorLe résultat n’a pas pu être jugé lors de cette vérification (par exemple, en cas d’échec du scrape ou de dégradation de l’évaluation).
Un résultat ne déclenche une alerte qu’une seule fois, lorsqu’il apparaît pour la première fois comme new. La déduplication repose uniquement sur l’URL canonique (le titre et l’extrait ne font délibérément pas partie de l’empreinte, donc un changement de titre ou d’extrait ne redéclenche pas d’alerte). Comme la clé est l’URL, un événement réel relayé par de nombreuses URL d’articles déclenche une alerte une fois par URL, et non une fois par événement. Modifier le goal ou les queries du monitor incrémente son goalVersion, ce qui invalide les verdicts précédents du juge. La réévaluation se fait de manière paresseuse plutôt que via un nouveau jugement global : les résultats existants ne sont pas tous rejugés d’un coup. À la place, chaque résultat est rejugé la prochaine fois qu’il réapparaît dans une vérification, et récupère alors le nouveau goalVersion. Les résultats qui ne réapparaissent pas conservent leur ancien verdict et leur goalVersion jusqu’à leur prochaine apparition.

​
Configuration partagée