Crawl

Crawler récursivement un site web et obtenir le contenu de chaque page

Le crawl soumet une URL à Firecrawl, découvre récursivement chaque sous-page accessible et en extrait le contenu. Elle gère automatiquement les sitemaps, le rendu JavaScript et les limites de débit, en renvoyant du Markdown propre ou des données structurées pour chaque page.

• Découvre les pages via le sitemap et le parcours récursif des liens
• Prend en charge le filtrage des chemins, les limites de profondeur et le contrôle des sous-domaines et des liens externes
• Renvoie les résultats via polling, WebSocket ou webhook

Chaque page extraite par un crawl passe par le même pipeline de scraping : tout ce que le scrape peut faire sur une page, le crawl peut le faire sur chaque page qu’il atteint. La page Fonctionnalités recense ces possibilités, indique où chaque fonctionnalité s’exécute et si elle nécessite une API key.

Essayez-le dans le Playground

Testez le crawl dans le Playground interactif — sans écrire de code.

​

Installation

Python

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(
  # Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  # api_key="fc-YOUR-API-KEY",
)

​

Utilisation de base

Soumettez une tâche de crawl en appelant POST /v2/crawl avec une URL de départ. Le point de terminaison renvoie un ID de tâche que vous utilisez pour interroger les résultats.

Python

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-VOTRE_CLÉ_API")

docs = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=10)
print(docs)

Chaque page crawlée consomme 1 crédit. La valeur par défaut de limit pour le crawl est de 10 000 pages. Avant de démarrer, le point de terminaison de crawl vérifie que vos crédits restants suffisent à couvrir la valeur de limit — sinon, il renvoie une erreur 402 (Paiement requis). Définissez une valeur de limit plus basse pour correspondre à la taille de crawl prévue (par exemple limit: 100) afin d’éviter ce problème. Des crédits supplémentaires s’appliquent pour certaines options : le mode JSON coûte 4 crédits supplémentaires par page, et l’analyse des PDF coûte 1 crédit par page de PDF.

​

Options de scrape

Toutes les options de l’point de terminaison Scrape sont disponibles dans crawl via scrapeOptions (JS) / scrape_options (Python). Elles s’appliquent à chaque page que le crawler extrait, y compris les formats, le proxy, la mise en cache, les actions, la localisation et les tags.

Python

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')

# Crawl avec des options de scrape
response = firecrawl.crawl('https://example.com',
    limit=100,
    scrape_options={
        'formats': [
            'markdown',
            { 'type': 'json', 'schema': { 'type': 'object', 'properties': { 'title': { 'type': 'string' } } } }
        ],
        'proxy': 'auto',
        'max_age': 600000,
        'only_main_content': True
    }
)

​

Vérification du statut du crawl

Utilisez l’ID du job pour interroger l’état du crawl et récupérer les résultats.

Python

status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

Les résultats des jobs de crawl sont disponibles via l’API pendant 24 heures après leur achèvement. Après cette période, vous pouvez toujours consulter l’historique de vos crawls et leurs résultats dans les journaux d’activité.

Les pages dans le tableau data des résultats de crawl sont des pages que Firecrawl a extraites avec succès, même si le site cible a renvoyé une erreur HTTP comme 404. Le champ metadata.statusCode indique le code de statut HTTP renvoyé par le site cible. Pour récupérer les pages que Firecrawl lui‑même n’a pas réussi à extraire (par exemple en cas d’erreurs réseau, d’expirations de délai ou de blocages liés à robots.txt), utilisez l’endpoint dédié Get Crawl Errors (GET /crawl/{id}/errors).

​

Gestion des réponses

La réponse varie selon l’état du crawl.

Pour les crawls non terminés ou les réponses volumineuses dépassant 10 Mo, un paramètre d’URL next est fourni. Vous devez appeler cette URL pour récupérer les 10 Mo de données suivants. Si le paramètre next est absent, cela indique la fin des données du crawl.

Les paramètres skip et next ne sont pertinents que lors d’appels directs à l’API. Si vous utilisez le SDK, la pagination est gérée automatiquement et tous les résultats sont renvoyés en une seule fois.

Scraping

{
  "status": "scraping",
  "total": 36,
  "completed": 10,
  "creditsUsed": 10,
  "expiresAt": "2024-00-00T00:00:00.000Z",
  "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=10",
  "data": [
    {
      "markdown": "[Page d’accueil de la documentation Firecrawl ![logo clair](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
      "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
      "metadata": {
        "title": "Créer un « chat avec un site web » avec Groq Llama 3 | Firecrawl",
        "language": "en",
        "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
        "description": "Découvrez comment utiliser Firecrawl, Groq Llama 3 et LangChain pour créer un bot de « chat avec votre site web ».",
        "ogLocaleAlternate": [],
        "statusCode": 200
      }
    },
    ...
  ]
}

​

Méthodes du SDK

Deux approches sont possibles pour utiliser crawl avec le SDK.

​

Crawler puis attendre

La méthode crawl attend la fin du crawl et renvoie la réponse complète. Elle gère automatiquement la pagination. Cela est recommandé pour la plupart des cas d’usage.

Python

from firecrawl import Firecrawl
from firecrawl.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# Crawler un site web :
crawl_status = firecrawl.crawl(
  'https://firecrawl.dev', 
  limit=100, 
  scrape_options=ScrapeOptions(formats=['markdown', 'html']),
  poll_interval=30
)
print(crawl_status)

La réponse inclut l’état du crawl et toutes les données extraites :

Python

success=True
status='completed'
completed=100
total=100
creditsUsed=100
expiresAt=datetime.datetime(2025, 4, 23, 19, 21, 17, tzinfo=TzInfo(UTC))
next=None
data=[
  Document(
    markdown='[Jour 7 - Semaine de lancement III. Journée des intégrations — du 14 au 20 avril](...',
    metadata={
      'title': '15 projets de web scraping en Python : du niveau débutant à avancé',
      ...
      'scrapeId': '97dcf796-c09b-43c9-b4f7-868a7a5af722',
      'sourceURL': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'url': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
      'statusCode': 200
    }
  ),
  ...
]

​

Démarrer et vérifier plus tard

La méthode startCrawl / start_crawl renvoie immédiatement un ID de crawl. Vous pouvez ensuite vérifier manuellement l’état. Utile pour les crawls de longue durée ou une logique de polling personnalisée.

Python

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
print(job)

# Vérifier l’état de l’exploration
status = firecrawl.get_crawl_status(job.id)
print(status)

La réponse initiale renvoie l’ID du job :

{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}

​

Résultats en temps réel avec WebSocket

La méthode watcher fournit des mises à jour en temps réel à mesure que les pages sont crawlées. Lancez un crawl, puis abonnez-vous aux événements pour traiter immédiatement les données.

Python

import asyncio
from firecrawl import AsyncFirecrawl

async def main():
    firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")

    # Démarrer d'abord un crawl
    started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)

    # Surveiller les mises à jour (instantanés) jusqu'au statut final
    async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
        if snapshot.status == "completed":
            print("DONE", snapshot.status)
            for doc in snapshot.data:
                print("DOC", doc.metadata.source_url if doc.metadata else None)
        elif snapshot.status == "failed":
            print("ERR", snapshot.status)
        else:
            print("STATUS", snapshot.status, snapshot.completed, "/", snapshot.total)

asyncio.run(main())

​

Webhooks

Vous pouvez configurer des webhooks pour recevoir des notifications en temps réel à mesure que votre crawl progresse. Cela vous permet de traiter les pages dès leur extraction, au lieu d’attendre la fin du crawl.

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["started", "page", "completed"]
      }
    }'

​

Types d’événements

Événement	Description
crawl.started	Se déclenche au démarrage du crawl
crawl.page	Se déclenche pour chaque page extraite avec succès
crawl.completed	Se déclenche à la fin du crawl
crawl.failed	Se déclenche si le crawl rencontre une erreur

​

Charge utile

{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Données de page pour les événements 'page'
  "metadata": {}, // Your custom metadata
  "error": null
}

​

Vérification des signatures de webhook

Chaque requête de webhook provenant de Firecrawl inclut un en-tête X-Firecrawl-Signature contenant une signature HMAC-SHA256. Vérifiez toujours cette signature pour vous assurer que le webhook est authentique et n’a pas été altéré.

1. Récupérez votre secret de webhook dans l’onglet Advanced des paramètres de votre compte
2. Extrayez la signature de l’en-tête X-Firecrawl-Signature
3. Calculez le HMAC-SHA256 du corps brut de la requête à l’aide de votre secret
4. Comparez-le avec l’en-tête de signature en utilisant une fonction sécurisée contre les attaques par temporisation

Ne traitez jamais un webhook sans vérifier d’abord sa signature. L’en-tête X-Firecrawl-Signature contient la signature au format : sha256=abc123def456...

Pour des exemples d’implémentation complets en JavaScript et Python, consultez la documentation sur la sécurité des webhooks. Pour une documentation complète sur les webhooks, y compris les charges utiles d’événements détaillées, la structure des charges utiles, la configuration avancée et le dépannage, consultez la documentation sur les webhooks.

​

Exécution et comptabilisation des résultats

Un crawl qui se termine n’équivaut pas à un crawl qui a atteint toutes les pages. Cette section décrit ce que les points de terminaison de crawl rapportent actuellement sur une exécution — les compteurs, le contrat de pagination, les enregistrements d’échec et les limites de portée — afin que vous puissiez juger par vous-même si une exécution est suffisamment complète pour en exploiter les résultats. Aucun de ces enregistrements ne garantit l’exhaustivité.

​

Lire les compteurs d’état

Chaque réponse de Get Crawl Status (GET /v2/crawl/{id}) contient les compteurs qui décrivent l’exécution :

Champ	Signification
status	L’une des valeurs scraping, completed, failed ou cancelled
total	completed plus les pages encore en cours de traitement : actives, en file d’attente et en attente de traitement. Les pages en échec ne sont pas comptabilisées.
completed	Le nombre de pages explorées avec succès
creditsUsed	Crédits consommés par le crawl jusqu’à présent
createdAt / completedAt / duration	Heure de début, heure de fin (états terminaux uniquement) et durée écoulée en secondes
expiresAt	Moment à partir duquel les résultats ne sont plus récupérables via l’API
next	URL de la page de résultats suivante de 10 Mo. Également renvoyé dès que status n’est pas completed — voir Parcourir les résultats par pages.

completed == total sur un crawl terminé ne signifie pas que toutes les pages découvertes ont abouti. Comme total additionne les pages complétées, actives, en file d’attente et en attente de traitement, en excluant celles en échec, un crawl en état terminal a toujours active, queued et backlog à zéro — les deux compteurs convergent donc, que des pages aient échoué ou non. Les compteurs d’état ne permettent pas de savoir si un échec s’est produit. Les pages en échec sont énumérées uniquement par Get Crawl Errors.

Le tableau data ne contient que les pages que Firecrawl a extraites avec succès. Les pages tentées qui n’ont jamais produit de résultat n’y figurent pas — récupérez-les via Get Crawl Errors, ci-dessous.

​

Parcourir les résultats page par page

Les réponses sont limitées à 10 Mo. Lorsqu’une réponse est tronquée, next contient l’URL de la page de résultats suivante.

next n’est pas seulement un signal indiquant qu’« il reste des données » : ce champ est également renvoyé dès que status n’est pas completed, si bien qu’un crawl dans l’état terminal failed ou cancelled peut fournir une URL next alors qu’il n’existe plus aucun résultat. N’utilisez pas l’absence de next comme condition de sortie de votre boucle : sur un crawl en échec ou annulé, ce champ ne disparaît jamais.

La condition terminale, c’est le champ d’état. Pour lire une exécution jusqu’au bout :

1. Interrogez GET /v2/crawl/{id} jusqu’à ce que status vaille completed, failed ou cancelled.
2. Tant que next est présent et que la dernière page a renvoyé un tableau data non vide, suivez next pour collecter les résultats restants.
3. Arrêtez-vous lorsque next est absent, ou lorsqu’une page ne renvoie aucun nouveau document.

Les SDKs officiels gèrent cette pagination pour vous et renvoient tous les résultats en une seule fois.

​

Pages en échec et bloquées

Get Crawl Errors (GET /v2/crawl/{id}/errors) recense les pages qui ne sont pas arrivées jusqu’à data. Ce point de terminaison renvoie deux tableaux :

• errors — les tâches de scraping en erreur, chacune avec id, url, error (le message d’erreur) et un timestamp de l’échec. Il s’agit des pages que Firecrawl lui-même n’a pas réussi à extraire : erreurs réseau, dépassements de délai et cas similaires. Les liens vers la page d’accueil d’un site externe volontairement ignorés sont signalés ici avec le code d’erreur EXTERNAL_LINK.
• robotsBlocked — les URL tentées mais bloquées par le fichier robots.txt du site.

Rien ne garantit que cette liste énumère l’intégralité des échecs : certaines classes d’échecs internes sont actuellement exclues de errors avant la construction de la réponse. Voyez-la comme le relevé des échecs signalés par Firecrawl, et non comme la preuve que rien d’autre n’a échoué. Le code d’erreur mentionné ci-dessus (EXTERNAL_LINK) est aujourd’hui renvoyé dans les objets d’erreur, mais ne fait pas encore partie du schema publié de GET /crawl/{id}/errors ; une mise à jour de la référence API est en attente.

Une page pour laquelle le site cible a renvoyé une erreur HTTP telle qu’un 404 n’est pas une erreur de crawl : Firecrawl l’a extraite avec succès, elle apparaît donc dans data avec le code d’état du site dans metadata.statusCode.

​

Ce que le crawler est autorisé à atteindre

La couverture est délimitée par les paramètres de portée que vous définissez, tous documentés dans la référence de configuration et la référence du point de terminaison Crawl :

• Enfants uniquement par défaut. Le crawl ignore les sous-liens qui ne sont pas des enfants de l’URL que vous fournissez. Utilisez crawlEntireDomain pour les chemins frères et parents, allowSubdomains pour les sous-domaines et allowExternalLinks pour suivre les liens hors du domaine.
• includePaths / excludePaths s’appliquent au chemin de l’URL, sous forme d’expressions régulières — et non à l’URL complète ni aux paramètres de requête. Définissez regexOnFullURL: true pour effectuer la correspondance sur l’URL complète, chaînes de requête incluses. L’URL de départ est elle aussi confrontée à includePaths : si elle ne correspond pas, le crawl peut renvoyer 0 page.
• Mode sitemap. Avec la valeur par défaut sitemap: "include", les URL proviennent du sitemap ainsi que de la découverte récursive de liens. "skip" n’utilise que les liens HTML, ce qui fait manquer les pages présentes uniquement dans le sitemap, comme les PDF ou les pages très imbriquées. "only" crawle le sitemap plus l’URL de départ, sans découvrir de liens depuis le HTML.
• maxDiscoveryDepth limite le nombre de sauts de découverte de liens suivis depuis la racine. Les pages situées à la profondeur maximale sont tout de même extraites, mais les liens qui s’y trouvent ne sont pas suivis.
• limit limite le nombre de pages, avec 10000 par défaut.
• ignoreQueryParameters évite d’extraire à nouveau le même chemin avec des paramètres de requête différents.
• Le fichier robots.txt est respecté, sauf si ignoreRobotsTxt est activé (Enterprise uniquement).

Par défaut, maxConcurrency correspond à la limite de concurrence de votre équipe, définie par votre offre — voir Limites de débit.

​

Quand les résultats varient d’une exécution à l’autre

Les résultats du crawl peuvent varier d’une exécution à l’autre avec la même configuration. Les pages sont extraites de manière concurrente, donc l’ordre dans lequel les liens sont découverts dépend du timing réseau et des pages qui finissent de se charger en premier. Cela signifie que différentes branches d’un site peuvent être explorées à des degrés divers à l’approche de la limite de profondeur, en particulier avec des valeurs élevées de maxDiscoveryDepth.

Pour rendre une exécution plus reproductible :

• Définissez maxConcurrency sur 1. Comme l’indique la référence de configuration, maxConcurrency correspond au « nombre maximal d’extractions concurrentes » — il limite le nombre de requests en cours simultanément. Cela réduit l’entrelacement dépendant du timing, mais n’élimine pas les variations d’une exécution à l’autre : la découverte du sitemap est mise en file en dehors de cette limite, les sitemaps imbriqués sont récupérés comme des jobs indépendants, et le tableau data renvoyé est ordonné selon l’heure de fin plutôt que selon l’ordre de découverte. Définir delay force également la concurrence à 1.
• Utilisez sitemap: "only" si le site dispose d’un sitemap complet, afin que l’ensemble des URL provienne du sitemap plutôt que de la découverte de liens.

​

Savoir quand un crawl est terminé

Si vous n’interrogez pas l’API, les événements webhook vous donnent la même information : crawl.page se déclenche pour chaque page extraite avec succès, et crawl.completed (ou crawl.failed) se déclenche à la fin de l’exécution. Les résultats d’un job restent récupérables via l’API pendant 24 heures après son achèvement ; passé ce délai, consultez-les dans les journaux d’activité.

​

Référence de configuration

Ensemble complet des paramètres disponibles lors de l’envoi d’une tâche de crawl :

Paramètre	Type	Par défaut	Description
url	string	(obligatoire)	URL de départ du crawl
limit	integer	10000	Nombre maximal de pages à crawler
maxDiscoveryDepth	integer	(aucun)	Profondeur maximale depuis l’URL racine en fonction des sauts de découverte de liens, et non du nombre de segments / dans l’URL. Chaque fois qu’une nouvelle URL est trouvée sur une page, une profondeur supérieure de 1 à celle de la page sur laquelle elle a été découverte lui est attribuée. Le site racine et les pages du sitemap ont une profondeur de découverte égale à 0. Les pages à la profondeur maximale sont tout de même extraites, mais les liens qu’elles contiennent ne sont pas suivis.
includePaths	string[]	(aucun)	Expressions régulières sur le chemin de l’URL à inclure. Seuls les chemins correspondants sont crawlés.
excludePaths	string[]	(aucun)	Expressions régulières sur le chemin de l’URL à exclure du crawl
regexOnFullURL	boolean	false	Applique includePaths/excludePaths à l’URL complète (y compris les paramètres de requête), et pas seulement au chemin
crawlEntireDomain	boolean	false	Suit les liens internes vers des URL sœurs ou parentes, et pas uniquement vers des chemins enfants
allowSubdomains	boolean	false	Suit les liens vers les sous-domaines du domaine principal
allowExternalLinks	boolean	false	Suit les liens vers des sites web externes. Les liens externes sont suivis sur un saut (leurs propres liens ne sont pas crawlés) et les liens pointant vers la page d’accueil d’un site externe sont ignorés — voir Liens externes.
sitemap	string	"include"	Gestion du sitemap : "include" (par défaut), "skip" ou "only"
ignoreQueryParameters	boolean	false	Évite d’extraire plusieurs fois le même chemin avec des paramètres de requête différents
ignoreRobotsTxt	boolean	false	Ignore les règles robots.txt du site web. Enterprise uniquement — contactez [e-mail] pour l’activer.
robotsUserAgent	string	(aucun)	Chaîne User-Agent personnalisée pour l’évaluation de robots.txt. Lorsqu’elle est définie, robots.txt est récupéré avec ce User-Agent et les règles sont évaluées par rapport à celui-ci au lieu de l’agent utilisateur par défaut. Enterprise uniquement — contactez [e-mail] pour l’activer.
delay	number	(aucun)	Délai, en secondes, entre les extractions afin de respecter les limites de débit. Le définir force la simultanéité à 1.
maxConcurrency	integer	(aucun)	Nombre maximal d’extractions simultanées. Utilise par défaut la limite de simultanéité de votre équipe.
scrapeOptions	object	(aucun)	Options appliquées à chaque page lors de l’extraction (formats, proxy, mise en cache, actions, etc.)
webhook	object	(aucun)	Configuration du webhook pour les notifications en temps réel
prompt	string	(aucun)	Prompt en langage naturel permettant de générer les options de crawl. Les paramètres explicitement définis remplacent les équivalents générés.

​

Détails importants

Par défaut, le crawl ignore les sous-liens qui ne dépendent pas de l’URL fournie. Par exemple, website.com/other-parent/blog-1 ne sera pas renvoyé si vous lancez un crawl sur website.com/blogs/. Utilisez le paramètre crawlEntireDomain pour inclure les chemins frères et parents. Pour inclure des sous-domaines comme blog.website.com lors du crawl de website.com, utilisez le paramètre allowSubdomains.

• Découverte du sitemap : Par défaut, le crawler inclut le sitemap du site pour découvrir les URL (sitemap: "include"). Si vous définissez sitemap: "skip", seules les pages accessibles via des liens HTML depuis l’URL racine seront trouvées. Les ressources comme les PDF ou les pages profondément imbriquées listées dans le sitemap mais non directement liées en HTML ne seront pas découvertes. Pour une couverture maximale, conservez le paramètre par défaut.
• Utilisation des crédits : Chaque page crawlée coûte 1 crédit. Le mode JSON ajoute 4 crédits par page, et l’analyse des PDF coûte 1 crédit par page de PDF.
• Expiration des résultats : Les résultats des jobs restent disponibles via l’API pendant 24 heures après leur exécution. Passé ce délai, vous pouvez consulter les résultats dans les journaux d’activité.
• Erreurs de crawl : Le tableau data contient les pages que Firecrawl a réussi à extraire. Utilisez le point de terminaison Get Crawl Errors pour récupérer les pages ayant échoué en raison d’erreurs réseau, de délais d’attente ou de blocages par robots.txt.

• Liens externes : Avec allowExternalLinks: true, le crawler suit les liens pointant hors de votre domaine et extrait chaque page liée une seule fois — il ne crawl ensuite pas les liens trouvés sur ces pages externes. Les liens vers la page d’accueil d’un site externe (une URL racine sans chemin, par exemple https://example.com/) sont intentionnellement ignorés afin d’éviter d’extraire un site entier sans rapport ; ils apparaissent dans Get Crawl Errors avec le code EXTERNAL_LINK. Les redirections sont suivies jusqu’à leur destination — y compris un lien qui se résout vers son URL canonique (par exemple http → https ou la variante www) — ainsi, seules les redirections qui aboutissent sur une page d’accueil externe sont ignorées.

• Résultats non déterministes : Les résultats du crawl peuvent varier d’une exécution à l’autre avec la même configuration, car les pages sont extraites de manière concurrente et l’ordre de découverte des liens dépend du timing réseau. Consultez Exécution et comptabilisation des résultats pour savoir ce qui varie et comment rendre une exécution plus reproductible.

Êtes-vous un agent IA qui a besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir des instructions d’intégration automatisée.