Passer au contenu principal
L’exploration 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 taux, 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

Essayez-le dans le Playground

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

​
Installation

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-VOTRE-CLE-API")

​
Utilisation de base

Soumettez une tâche d’exploration 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. 
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 explorée consomme 1 crédit. La valeur par défaut de limit pour l’exploration est de 10 000 pages. Définissez une valeur de limit plus basse pour contrôler l’utilisation des crédits (par exemple limit: 100). Des crédits supplémentaires s’appliquent pour certaines options : le mode JSON coûte 4 crédits supplémentaires par page, le proxy amélioré 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’endpoint 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. 
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. 
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.
{
  "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. 
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 : 
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. 
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. 
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énementDescription
crawl.startedSe déclenche au démarrage du crawl
crawl.pageSe déclenche pour chaque page extraite avec succès
crawl.completedSe déclenche à la fin du crawl
crawl.failedSe 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.

​
Référence de configuration

Ensemble complet des paramètres disponibles lors de l’envoi d’une tâche de crawl :
ParamètreTypePar défautDescription
urlstring(obligatoire)URL de départ du crawl
limitinteger10000Nombre maximal de pages à crawler
maxDiscoveryDepthinteger(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 scrapées, mais les liens qu’elles contiennent ne sont pas suivis.
includePathsstring[](aucun)Expressions régulières sur le chemin de l’URL à inclure. Seuls les chemins correspondants sont crawlés.
excludePathsstring[](aucun)Expressions régulières sur le chemin de l’URL à exclure du crawl
regexOnFullURLbooleanfalseApplique includePaths/excludePaths à l’URL complète (y compris les paramètres de requête), et pas seulement au chemin
crawlEntireDomainbooleanfalseSuit les liens internes vers des URL sœurs ou parentes, et pas uniquement vers des chemins enfants
allowSubdomainsbooleanfalseSuit les liens vers les sous-domaines du domaine principal
allowExternalLinksbooleanfalseSuit les liens vers des sites web externes
sitemapstring"include"Gestion du sitemap : "include" (par défaut), "skip" ou "only"
ignoreQueryParametersbooleanfalseÉvite de scraper plusieurs fois le même chemin avec des paramètres de requête différents
delaynumber(aucun)Délai, en secondes, entre les scrapes afin de respecter les limites de débit
maxConcurrencyinteger(aucun)Nombre maximal de scrapes simultanés. Utilise par défaut la limite de simultanéité de votre équipe.
scrapeOptionsobject(aucun)Options appliquées à chaque page lors du scrape (formats, proxy, mise en cache, actions, etc.)
webhookobject(aucun)Configuration du webhook pour les notifications en temps réel
promptstring(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, le proxy avancé 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.
  • Résultats non déterministes : 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 obtenir des résultats plus déterministes, définissez maxConcurrency sur 1 ou utilisez sitemap: "only" si le site dispose d’un sitemap complet.