Firecrawl explore efficacement les sites web pour extraire des données complètes tout en contournant les blocages. Le processus :
  1. Analyse de l’URL : Analyse le sitemap et parcourt le site pour identifier les liens
  2. Exploration : Suit les liens de façon récursive pour trouver toutes les sous-pages
  3. Scraping : Extrait le contenu de chaque page, en gérant le JavaScript et les limites de débit
  4. Résultats : Convertit les données en Markdown propre ou en format structuré
Cela garantit une collecte de données exhaustive à partir de n’importe quelle URL de départ.

​
Crawl

​
point de terminaison /crawl

Permet d’explorer une URL et toutes ses sous-pages accessibles. Cette opération crée une tâche de crawl et renvoie un ID de tâche pour suivre l’état du crawl.
Par défaut, le crawl ignore les sous-liens d’une page s’ils ne sont pas des enfants de l’URL fournie. Ainsi, website.com/other-parent/blog-1 ne sera pas renvoyé si vous avez crawlé website.com/blogs/. Si vous souhaitez inclure website.com/other-parent/blog-1, utilisez le paramètre crawlEntireDomain. Pour explorer des sous-domaines comme blog.website.com lors du crawl de website.com, utilisez le paramètre allowSubdomains.

​
Installation

# pip install firecrawl-py

from firecrawl import Firecrawl

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

​
Utilisation

from firecrawl import Firecrawl

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

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

​
Options de scraping dans crawl

Toutes les options du point de terminaison /scrape sont disponibles dans crawl via scrapeOptions (JS) / scrape_options (Python). Elles s’appliquent à chaque page que le crawler récupère : formats, proxy, mise en cache, actions, localisation, tags, etc. Consultez la liste complète dans la référence de l’API Scrape. 
import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// Crawl with scrape options
const crawlResponse = await firecrawl.crawl('https://example.com', {
  limit: 100,
  scrapeOptions: {
    formats: [
      'markdown',
      { type: 'json', schema: { type: 'object', properties: { title: { type: 'string' } } } }
    ],
    proxy: 'auto',
    maxAge: 600000,
    onlyMainContent: true
  }
});

​
Réponse de l’API

Si vous utilisez cURL ou la méthode starter, un ID sera renvoyé pour vérifier l’état du crawl.
Si vous utilisez le SDK, consultez les méthodes ci-dessous pour comprendre le comportement waiter vs starter.
{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}

​
Vérifier une tâche de crawl

Permet de vérifier l’état d’une tâche de crawl et d’obtenir son résultat.
Ce point de terminaison fonctionne uniquement pour les crawls en cours ou ceux qui viennent de se terminer. 
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

​
Gestion de la réponse

La réponse varie selon l’état du crawl. Pour les réponses non terminées ou 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 signifie que vous avez atteint la fin des données du crawl. Le paramètre skip définit le nombre maximal de résultats renvoyés pour chaque lot de résultats.
Les paramètres skip et next ne sont pertinents que lorsque vous appelez directement l’API. Si vous utilisez le SDK, nous gérons cela pour vous et renvoyons tous les résultats 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 le SDK :
  1. Crawler puis attendre (crawl) :
    • Attend la fin du crawl et renvoie la réponse complète
    • Gère automatiquement la pagination
    • Recommandé pour la plupart des cas d’usage
from firecrawl import Firecrawl, ScrapeOptions

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

# Explorer 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
    }
  ),
  ...
]
  1. Démarrer puis vérifier l’état (startCrawl/start_crawl) :
    • Renvoie immédiatement un ID de crawl
    • Permet une vérification manuelle de 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)

# Check the status of the crawl
status = firecrawl.get_crawl_status(job.id)
print(status)

​
WebSocket de crawl

La méthode WebSocket de Firecrawl, « Crawl URL and Watch », permet l’extraction et la supervision des données en temps réel. Lancez un crawl à partir d’une URL et personnalisez-le avec des options comme des limites de pages, des domaines autorisés et des formats de sortie — idéal pour le traitement immédiat des données. 
import asyncio
from firecrawl import AsyncFirecrawl

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

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

    # Suivre les mises à jour (snapshots) jusqu’au statut final
    async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
        if snapshot.status == "completed":
            print("TERMINE", snapshot.status)
            for doc in snapshot.data:
                print("DOC", doc.metadata.sourceURL if doc.metadata else None)
        elif snapshot.status == "failed":
            print("ERREUR", snapshot.status)
        else:
            print("STATUT", snapshot.status, snapshot.completed, "/", snapshot.total)

asyncio.run(main())

​
Webhook de crawl

Vous pouvez configurer des webhooks pour recevoir des notifications en temps réel à mesure que votre crawl avance. Cela vous permet de traiter les pages dès qu’elles sont extraites, au lieu d’attendre la fin complète 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"]
      }
    }'
Pour une documentation complète sur les webhooks, incluant les types d’événements, la structure des charges utiles et des exemples d’implémentation, consultez la documentation sur les webhooks.

​
Référence rapide

Types d’événements :
  • crawl.started - Au début de l’exploration
  • crawl.page - Pour chaque page extraite avec succès
  • crawl.completed - À la fin de l’exploration
  • crawl.failed - Si l’exploration rencontre une erreur
Payload de base : 
{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Données de page pour les événements « page »
  "metadata": {}, // Vos métadonnées personnalisées
  "error": null
}
Pour des informations détaillées sur la configuration des webhooks, les bonnes pratiques de sécurité et le dépannage, consultez la documentation sur les webhooks.