Passer au contenu principal
Firecrawl explore efficacement les sites web pour extraire des données complètes tout en gérant une infrastructure web complexe. Le processus :
  1. Analyse d’URL : Parcourt le sitemap et le site pour identifier les liens
  2. Parcours : Suit les liens de manière récursive afin de trouver toutes les sous-pages
  3. Scraping : Extrait le contenu de chaque page, en gérant le JavaScript et les limites de taux
  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

​
/crawl endpoint

Permet d’explorer une URL et toutes les sous-pages accessibles. Soumet un travail d’exploration et renvoie un ID de tâche pour suivre l’état de l’exploration.
Par défaut, 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 explorez website.com/blogs/. Si vous souhaitez website.com/other-parent/blog-1, utilisez le paramètre crawlEntireDomain. Pour explorer des sous-domaines comme blog.website.com lors de l’exploration de website.com, utilisez le paramètre allowSubdomains.
Par défaut, le crawler inclut le sitemap du site pour découvrir des URL (sitemap: "include"). Si vous définissez sitemap: "skip", le crawler ne trouvera que les pages accessibles via des liens HTML à partir de l’URL racine. Les ressources comme les PDF ou les pages très profondément imbriquées qui sont listées dans le sitemap mais non liées directement depuis une page HTML seront ignorées. Pour une couverture maximale, conservez le paramètre par défaut sitemap: "include".

​
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)
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 dans crawl

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 : 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 avec des options de scrape
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, cela renverra un ID 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 un job de crawl

Permet de consulter l’état d’un job de crawl et d’en récupérer le résultat.
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).
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

​
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. Le paramètre skip définit le nombre maximal de résultats renvoyés pour chaque segment de résultats.
Les paramètres skip et next ne sont pertinents que lors d’appels directs à l’API. Si vous utilisez le SDK, nous gérons cela pour vous et renverrons 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
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
    }
  ),
  ...
]
  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)

# Vérifier l’état de l’exploration
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 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())

​
Webhook de crawl

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"]
      }
    }'

​
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 échoue
Charge utile de base : 
{
  "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
}

​
Sécurité : 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é. Fonctionnement :
  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.

​
Documentation complète

Pour une documentation complète des webhooks, incluant le détail des payloads d’événements, la structure des payloads, la configuration avancée et le dépannage, consultez la documentation Webhooks.