​
Installation

Pour installer le SDK Python Firecrawl, utilisez pip :
Python
# pip install firecrawl-py

from firecrawl import Firecrawl

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

​
Utilisation

  1. Récupérez une clé API sur firecrawl.dev
  2. Définissez la clé API comme variable d’environnement nommée FIRECRAWL_API_KEY ou passez-la en paramètre à la classe Firecrawl.
Voici un exemple d’utilisation du SDK :
Python
from firecrawl import Firecrawl

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

# Extraire le contenu d’un site :
scrape_status = firecrawl.scrape(
  'https://firecrawl.dev', 
  formats=['markdown', 'html']
)
print(scrape_status)

# Explorer un site :
crawl_status = firecrawl.crawl(
  'https://firecrawl.dev', 
  limit=100, 
  scrape_options={
    'formats': ['markdown', 'html']
  }
)
print(crawl_status)

​
Extraction d’une URL

Pour extraire une URL unique, utilisez la méthode scrape. Elle prend l’URL en paramètre et renvoie le document extrait.
Python
# Scrape a website:
scrape_result = firecrawl.scrape('firecrawl.dev', formats=['markdown', 'html'])
print(scrape_result)

​
Explorer un site web

Pour explorer un site web, utilisez la méthode crawl. Elle prend en arguments l’URL de départ et des options facultatives. Ces options permettent de définir des paramètres supplémentaires pour la tâche d’exploration, comme le nombre maximal de pages à parcourir, les domaines autorisés et le format de sortie. Consultez Pagination pour la pagination automatique/manuelle et les limites.
Python
job = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=5, poll_interval=1, timeout=120)
print(job)

​
Démarrer un crawl

Vous préférez ne pas bloquer l’exécution ? Consultez la section Classe Async ci-dessous.
Lancez une tâche sans attendre avec start_crawl. Elle renvoie un ID de tâche que vous pouvez utiliser pour vérifier l’état. Utilisez crawl lorsque vous voulez un attenteur qui bloque jusqu’à la fin. Voir Pagination pour le comportement et les limites de pagination.
Python
job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
print(job)

​
Vérifier l’état d’un crawl

Pour connaître l’état d’un job de crawl, utilisez la méthode get_crawl_status. Elle prend l’ID du job en paramètre et renvoie l’état actuel du crawl.
Python
status = firecrawl.get_crawl_status("<crawl-id>")
print(status)

​
Annuler un crawl

Pour annuler une tâche de crawl, utilisez la méthode cancel_crawl. Elle prend l’ID du job renvoyé par start_crawl en paramètre et retourne l’état de l’annulation.
Python
ok = firecrawl.cancel_crawl("<crawl-id>")
print("Annulation :", ok)

​
Cartographier un site web

Utilisez map pour générer une liste d’URL à partir d’un site web. Les options permettent d’adapter le processus de cartographie, par exemple en excluant les sous-domaines ou en s’appuyant sur le sitemap.
Python
res = firecrawl.map(url="https://firecrawl.dev", limit=10)
print(res)

​
Exploration d’un site web avec WebSockets

Pour explorer un site web avec WebSockets, lancez la tâche avec start_crawl et abonnez-vous à l’aide du helper watcher. Créez un watcher avec l’ID de la tâche et attachez des gestionnaires (par exemple pour page, completed, failed) avant d’appeler start().
Python
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())
Les points de terminaison Firecrawl pour crawl et batch renvoient une URL next lorsqu’il reste des données. Le SDK Python effectue par défaut une pagination automatique et agrège tous les documents ; dans ce cas, next vaut None. Vous pouvez désactiver l’auto‑pagination ou définir des limites.

​
Crawl

Utilisez la méthode « waiter » crawl pour l’approche la plus simple, ou démarrez un job et paginez manuellement.
Crawl simple (pagination automatique, par défaut)
Exploration manuelle avec contrôle de la pagination (page unique)
  • Lancez une tâche, puis récupérez les pages une par une avec auto_paginate=False.
Python
crawl_job = client.start_crawl("https://example.com", limit=100)

status = client.get_crawl_status(crawl_job.id, pagination_config=PaginationConfig(auto_paginate=False))
print("explorer une seule page :", status.status, "documents :", len(status.data), "suivant :", status.next)
Exploration manuelle avec limites (pagination automatique + arrêt anticipé)
  • Laissez la pagination automatique activée, mais arrêtez plus tôt avec max_pages, max_results ou max_wait_time.
Python
status = client.get_crawl_status(
    crawl_job.id,
    pagination_config=PaginationConfig(max_pages=2, max_results=50, max_wait_time=15),
)
print("crawl limité :", status.status, "docs :", len(status.data), "suivant :", status.next)

​
Scrape par lots

Utilisez la méthode de waiter batch_scrape, ou lancez un job et paginez manuellement.
Extraction par lot simple (pagination automatique, par défaut)
Scraping par lots manuel avec contrôle de la pagination (page unique)
  • Démarrez un job, puis récupérez une page à la fois avec auto_paginate=False.
Python
batch_job = client.start_batch_scrape(urls)
status = client.get_batch_scrape_status(batch_job.id, pagination_config=PaginationConfig(auto_paginate=False))
print("lot, une seule page :", status.status, "docs :", len(status.data), "suivant :", status.next)
Extraction par lots manuelle avec limites (pagination automatique + arrêt anticipé)
  • Laissez la pagination automatique activée, mais arrêtez plus tôt avec max_pages, max_results ou max_wait_time.
Python
status = client.get_batch_scrape_status(
    batch_job.id,
    pagination_config=PaginationConfig(max_pages=2, max_results=100, max_wait_time=20),
)
print("lot limité :", status.status, "docs :", len(status.data), "suivant :", status.next)

​
Gestion des erreurs

Le SDK gère les erreurs renvoyées par l’API Firecrawl et déclenche des exceptions appropriées. En cas d’erreur lors d’une requête, une exception est levée avec un message d’erreur explicite.

​
Classe asynchrone

Pour les opérations asynchrones, utilisez la classe AsyncFirecrawl. Ses méthodes sont identiques à celles de Firecrawl, mais elles ne bloquent pas le thread principal.
Python
import asyncio
from firecrawl import AsyncFirecrawl

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

    # Scraping
    doc = await firecrawl.scrape("https://firecrawl.dev", formats=["markdown"])  # type: ignore[arg-type]
    print(doc.get("markdown"))

    # Recherche
    results = await firecrawl.search("firecrawl", limit=2)
    print(results.get("web", []))

    # Crawl (démarrage + statut)
    started = await firecrawl.start_crawl("https://docs.firecrawl.dev", limit=3)
    status = await firecrawl.get_crawl_status(started.id)
    print(status.status)

    # Scraping par lot (attente)
    job = await firecrawl.batch_scrape([
        "https://firecrawl.dev",
        "https://docs.firecrawl.dev",
    ], formats=["markdown"], poll_interval=1, timeout=60)
    print(job.status, job.completed, job.total)

asyncio.run(main())