Python - Firecrawl Docs

Installation#

Pour installer le SDK Python Firecrawl, utilisez pip :

Python

# pip install firecrawl-pyfrom firecrawl import Firecrawlfirecrawl = 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#

Récupérez une clé API sur firecrawl.dev, puis définissez-la comme variable d’environnement FIRECRAWL_API_KEY ou passez-la directement à la classe Firecrawl.

Note

Pas de clé API ? Vous pouvez instancier Firecrawl sans clé et utiliser scrape, search et interact dans l’offre Free sans clé (avec une limite de débit par IP — voir Limites de débit). Toutes les autres méthodes nécessitent une clé.

Python

from firecrawl import Firecrawlfirecrawl = 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 renvoie le contenu de la page sous forme de donnée structurée, y compris le markdown, les métadonnées et tous les autres formats demandés.

Python

# Extraire un site web :scrape_result = firecrawl.scrape('firecrawl.dev', formats=['markdown', 'html'])print(scrape_result)

Note

Le SDK Python convertit tous les noms de champs de la réponse de camelCase en snake_case. Par exemple, les champs de métadonnées tels que ogImage, ogTitle et sourceURL de l’API deviennent og_image, og_title et source_url dans la réponse du SDK.

Analyse des fichiers envoyés#

Utilisez parse pour envoyer des fichiers locaux (html, pdf, docx, xlsx, etc.) directement à /v2/parse. parse ne prend pas en charge changeTracking ni les options réservées au navigateur, comme actions, wait_for, location, mobile, screenshot et branding.

Python

from firecrawl.v2.types import ParseOptionsparsed = firecrawl.parse(    b"<!DOCTYPE html><html><body><h1>Python Parse</h1></body></html>",    filename="upload.html",    content_type="text/html",    options=ParseOptions(formats=["markdown"]),)print(parsed.markdown)

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)

Exploration du sitemap uniquement#

Utilisez sitemap="only" pour explorer uniquement les URL du sitemap (l’URL de départ est toujours incluse et la découverte de liens HTML est ignorée).

Python

job = firecrawl.crawl(url="https://docs.firecrawl.dev", sitemap="only", limit=25)print(job.status, len(job.data))

Démarrer un crawl#

Tip

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#

Vérifiez l’état d’une tâche de crawl avec get_crawl_status. Indiquez l’ID de tâche pour obtenir l’état actuel ainsi que les résultats déjà collectés.

Python

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

Annuler un crawl#

Annulez une tâche de crawl avec la méthode cancel_crawl. Passez l’ID de tâche renvoyé par start_crawl pour obtenir 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)

Exécuter un agent#

Confiez une tâche de recherche ou d’extraction à un agent à l’aide de la méthode agent. Elle accepte un prompt, un schema facultatif pour structurer la sortie et max_credits pour limiter les crédits que l’exécution peut consommer.

Python

from firecrawl import Firecrawlfrom pydantic import BaseModel, Fieldfrom typing import List, Optionalapp = Firecrawl(api_key="fc-YOUR_API_KEY")class Founder(BaseModel):    name: str = Field(description="Full name of the founder")    role: Optional[str] = Field(None, description="Role or position")    background: Optional[str] = Field(None, description="Professional background")class FoundersSchema(BaseModel):    founders: List[Founder] = Field(description="List of founders")result = app.agent(    prompt="Find the founders of Firecrawl",    schema=FoundersSchema,    model="spark-2",    max_credits=100)print(result.data)

Les exécutions d’agent sont asynchrones. Utilisez start_agent pour obtenir immédiatement un ID de tâche, puis interrogez son état avec get_agent_status.

Python

from firecrawl import Firecrawlapp = Firecrawl(api_key="fc-YOUR_API_KEY")# Démarrer une tâche d'agentagent_job = app.start_agent(    prompt="Find the founders of Firecrawl")# Check the statusstatus = app.get_agent_status(agent_job.id)print(status)# Example output:# status='completed'# success=True# data={ ... }# expires_at=datetime.datetime(...)# credits_used=15

Chaque exécution enregistre également une trace d’exécution et des instantanés de sortie, que vous pouvez consulter avec get_agent_trace et get_agent_snapshot. Consultez Agent pour le schéma des événements et la liste complète des paramètres.

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 asynciofrom firecrawl import AsyncFirecrawlasync 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())

Pagination#

Les points de terminaison Firecrawl pour crawl et batch scrape 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 pour contrôler le comportement de la pagination.

PaginationConfig#

Utilisez PaginationConfig pour contrôler le comportement de la pagination lorsque vous appelez get_crawl_status ou get_batch_scrape_status :

Python

from firecrawl.v2.types import PaginationConfig

Option	Type	Par défaut	Description
`auto_paginate`	`bool`	`True`	Lorsque `True`, récupère automatiquement toutes les pages et agrège les résultats. Définissez sur `False` pour récupérer les pages une par une.
`max_pages`	`int`	`None`	S'arrête après avoir récupéré ce nombre de pages (s'applique uniquement lorsque `auto_paginate=True`).
`max_results`	`int`	`None`	S'arrête après avoir collecté ce nombre de documents (s'applique uniquement lorsque `auto_paginate=True`).
`max_wait_time`	`int`	`None`	S'arrête après ce nombre de secondes (s'applique uniquement lorsque `auto_paginate=True`).

Aides à la pagination manuelle#

Lorsque auto_paginate=False, la réponse inclut une URL next si davantage de données sont disponibles. Utilisez ces méthodes utilitaires pour récupérer les pages suivantes :

get_crawl_status_page(next_url) - Récupère la page suivante des résultats de crawl en utilisant l'URL opaque next provenant d'une réponse précédente.
get_batch_scrape_status_page(next_url) - Récupère la page suivante des résultats de scraping par lot en utilisant l'URL opaque next provenant d'une réponse précédente.

Ces méthodes renvoient le même type de réponse que l'appel de statut initial, y compris une nouvelle URL next s'il reste d'autres pages.

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)

Voir le flux par défaut dans Explorer un site web.

Crawl manuel avec contrôle de la pagination

Démarrez un job, puis récupérez une page à la fois avec auto_paginate=False. Utilisez get_crawl_status_page pour récupérer les pages suivantes :

Python

crawl_job = client.start_crawl("https://example.com", limit=100)# Fetch first pagestatus = client.get_crawl_status(    crawl_job.id,    pagination_config=PaginationConfig(auto_paginate=False))print("First page:", len(status.data), "docs")# Récupérer les pages suivantes avec get_crawl_status_pagewhile status.next:    status = client.get_crawl_status_page(status.next)    print("Next page:", len(status.data), "docs")

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)

Voir le parcours par défaut dans Batch Scrape.

Scraping par lot manuel avec contrôle de la pagination

Lancez une tâche, puis récupérez les résultats page par page avec auto_paginate=False. Utilisez get_batch_scrape_status_page pour récupérer les pages suivantes :

Python

batch_job = client.start_batch_scrape(urls)# Fetch first pagestatus = client.get_batch_scrape_status(    batch_job.id,    pagination_config=PaginationConfig(auto_paginate=False))print("First page:", len(status.data), "docs")# Récupérer les pages suivantes avec get_batch_scrape_status_pagewhile status.next:    status = client.get_batch_scrape_status_page(status.next)    print("Next page:", len(status.data), "docs")

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#

Lorsqu'une requête échoue, le SDK lève une exception accompagnée d'un message descriptif indiquant l'origine du problème. Entourez vos appels de try/except pour intercepter ces exceptions et gérer les erreurs dans votre application.

Classe asynchrone#

Pour les opérations asynchrones, utilisez la classe AsyncFirecrawl. Ses méthodes reprennent celles de Firecrawl, mais elles ne bloquent pas le thread principal.

Python

import asynciofrom firecrawl import AsyncFirecrawlasync 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())

Python

from firecrawl import AsyncFirecrawlasync_firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")parsed = await async_firecrawl.parse(    b"<!DOCTYPE html><html><body><h1>Async Parse</h1></body></html>",    filename="upload.html",    content_type="text/html",)

Navigateur#

Lancez des sessions de navigateur dans le cloud et exécutez du code à distance.

Créer une session#

Python

from firecrawl import Firecrawlapp = Firecrawl(api_key="fc-YOUR-API-KEY")session = app.browser()print(session.id)             # ID de sessionprint(session.cdp_url)        # wss://cdp-proxy.firecrawl.dev/cdp/...print(session.live_view_url)  # https://liveview.firecrawl.dev/...

Exécuter du code#

Python

result = app.browser_execute(    session.id,    code='await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',    language="python",)print(result.result)  # "Hacker News"

Exécuter JavaScript plutôt que Python :

Python

result = app.browser_execute(    session.id,    code='await page.goto("https://example.com"); const t = await page.title(); console.log(t);',    language="node",)

Profils#

Enregistrez et réutilisez l'état du navigateur (cookies, localStorage, etc.) d'une session à l'autre :

Python

session = app.browser(    ttl=600,    profile={        "name": "my-profile",        "save_changes": True,    },)

Connexion via le CDP#

Pour un contrôle total de Playwright, connectez-vous directement en utilisant l’URL du CDP :

Python

from playwright.sync_api import sync_playwrightwith sync_playwright() as p:    browser = p.chromium.connect_over_cdp(session.cdp_url)    context = browser.contexts[0]    page = context.pages[0] if context.pages else context.new_page()    page.goto("https://example.com")    print(page.title())    browser.close()

Lister & fermer des sessions#

Python

# Lister les sessions activessessions = app.list_browsers(status="active")for s in sessions.sessions:    print(s.id, s.status, s.created_at)# Fermer une sessionapp.delete_browser(session.id)

Session interactive liée au scrape#

Utilisez un ID de tâche de scrape pour continuer à interagir avec le contexte de page rejoué issu de ce scrape :

interact(job_id, ...) exécute du code dans la session de navigateur liée au scrape.
Le premier appel à interact initialise automatiquement la session à partir du contexte du scrape.
Les appels suivants à interact sur le même ID de tâche réutilisent cet état actif du navigateur.
stop_interaction(job_id) arrête la session interactive une fois que vous avez terminé.

Python

doc = app.scrape(    "https://example.com",    actions=[{"type": "click", "selector": "a[href='/pricing']"}],)scrape_job_id = doc.metadata_typed.scrape_idif not scrape_job_id:    raise RuntimeError("Missing scrape job id")run = app.interact(    scrape_job_id,    code="print(await page.url())",    language="python",    timeout=60,)print(run.stdout)app.stop_interaction(scrape_job_id)

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