Firecrawl récupère une page web, la rend dans un navigateur headless et renvoie du markdown propre au lieu du HTML brut. Le dépôt firecrawl/firecrawl compte environ 170 mille étoiles, le code du serveur est sous AGPL-3.0, et les SDK officiels sous MIT. Cette répartition des licences est la première chose à vérifier avant un déploiement commercial, car elle s'applique à des couches du système entièrement différentes.
Ce que fait réellement Firecrawl
La tâche paraît triviale : prendre une adresse, renvoyer du texte. En pratique, plusieurs couches s'intercalent entre les deux, chacune doit être traitée séparément, et ensemble elles décident si une solution maison prend une semaine ou six mois.
La première couche est la récupération. Une grande partie des sites modernes renvoie à l'adresse un document HTML presque vide, avec un script qui construit le contenu dans le navigateur ensuite. Une simple requête HTTP reçoit alors un squelette sans une seule phrase. Firecrawl exécute la page dans un navigateur piloté par défaut par Playwright, attend le rendu, et ne lit l'arbre du document qu'ensuite.
La deuxième couche est le nettoyage. Un document rendu contient des menus de navigation, un pied de page, une bannière de consentement aux cookies, une section d'articles associés et une dizaine d'autres blocs qui sont du pur bruit pour un modèle de langage. L'option onlyMainContent, activée par défaut, essaie de ne garder que le corps du contenu. Pour un réglage manuel, il y a includeTags et excludeTags, qui acceptent tous deux des sélecteurs CSS.
La troisième couche est la conversion. L'arbre du document nettoyé devient du markdown dans lequel les titres, les listes, les tableaux et les blocs de code gardent leur structure. Un modèle de langage traite ce format nettement mieux que le HTML, et le même texte coûte moins de tokens au passage, puisque les attributs de classe et les identifiants disparaissent.
Ce que Firecrawl ne fait pas compte tout autant. Il ne découpe pas le texte en chunks, ne calcule pas de vecteurs et ne stocke rien à long terme. Le résultat doit être découpé et placé vous-même dans un magasin vectoriel, par exemple Chroma ou Pinecone. Ce n'est pas non plus une bibliothèque qui tourne dans votre processus. C'est un service HTTP, et les SDK JavaScript et Python sont des clients légers qui assemblent une requête et décodent une réponse.
La licence AGPL-3.0 et ses conséquences
C'est la section la plus importante ici, car c'est là que se retrouvent bloqués la plupart des déploiements qui ont sauté la vérification.
Le fichier LICENSE à la racine du dépôt porte le texte complet de la GNU Affero General Public License version 3, avec une mention de copyright de Sideguide Technologies Inc. Il n'y a aucune clause supplémentaire, ni Commons Clause, ni restriction de concurrence. C'est de l'AGPL-3.0 pure et non modifiée, et l'interface de GitHub la reconnaît correctement en indiquant agpl-3.0.
Le README l'énonce plus précisément : le projet est principalement sous licence AGPL-3.0, tandis que les SDK et certains composants d'interface sont sous MIT. Cette répartition peut se vérifier dans le code. Les répertoires apps/js-sdk et apps/python-sdk portent leurs propres fichiers LICENSE avec du texte MIT. Le répertoire apps/api, qui est le serveur, n'a pas de fichier propre et relève donc de la licence racine.
Trois sources indépendantes concordent pour les seuls SDK, ce qui, avec des projets de ce genre, n'est pas la règle. Le paquet firecrawl en version 4.34.1 déclare un champ license valant MIT dans le registre npm, et après téléchargement et extraction de l'archive, package/LICENSE contient bien du texte MIT avec la mention de Sideguide Technologies Inc. Son homologue Python, firecrawl-py en version 4.37.1, déclare aussi MIT dans ses métadonnées PyPI. Le paquet firecrawl-mcp est distribué sous MIT, et l'outil en ligne de commande firecrawl-cli sous ISC.
La conclusion pratique est la suivante. Si vous utilisez le service cloud et l'appelez via un SDK, le code que vous écrivez ne touche que la couche MIT et il n'y a pas de problème. Si en revanche vous montez vous-même le serveur, vous entrez en territoire AGPL-3.0, dont la section treize couvre quelque chose que la GPL ordinaire ne couvre pas : un utilisateur qui interagit avec le programme par le réseau a le droit de recevoir le code source de la version à laquelle il se connecte, si elle a été modifiée.
Il n'y a pas d'exception pour l'auto-hébergement. Ni le fichier de licence ni la documentation n'accordent de permission supplémentaire qui lèverait cette obligation. Il n'existe pas non plus de double licence annoncée publiquement que vous pourriez acheter pour votre propre déploiement. La voie commerciale exempte d'exposition au copyleft reste le service cloud ou un accord Enterprise négocié individuellement.
Une question distincte et non tranchée est celle de la frontière d'une œuvre dérivée quand votre application parle à un serveur Firecrawl uniquement par HTTP et tourne dans un conteneur séparé. Certaines équipes juridiques jugent cette séparation suffisante, d'autres non. Ce n'est pas un avis juridique, seulement la description de l'état des choses : si vous prévoyez d'auto-héberger dans un produit commercial, cette décision revient à un juriste plutôt qu'à l'équipe d'ingénierie.
Les endpoints et leurs différences
L'interface en version deux expose plusieurs opérations dont les noms se confondent, et chacune a un coût différent.
L'opération scrape récupère une adresse et renvoie un document dans les formats demandés. L'opération crawl découvre les sous-pages et les récupère toutes, en fonctionnant de façon asynchrone : vous recevez un identifiant de tâche et interrogez son statut. L'opération map renvoie seulement une liste d'adresses, sans contenu, ce qui est la façon la moins chère de voir la taille d'un site avant de lancer la vraie récupération.
L'opération search combine une recherche web avec la récupération des résultats, en acceptant les sources web, news et images ainsi que des catégories comme github ou pdf. L'opération parse traite un fichier téléversé au lieu d'une adresse. S'y ajoutent batch scrape pour une liste d'adresses, extract et agent pour extraire des données décrites en une phrase, monitor pour surveiller des pages selon un calendrier, et interact plus browser pour les sessions de navigateur.
La distinction entre map et crawl vaut d'être retenue, car l'erreur coûte cher. Le mapping compte pour un crédit par appel, tandis que la récupération compte pour un crédit par page. Lancer crawl sur un grand site uniquement pour savoir combien de sous-pages il a peut consommer tout un quota mensuel en quelques minutes.
Installation et premier appel
Le client JavaScript exige Node 22 ou plus récent, ce qui est dit explicitement dans le champ engines du paquet. Le client Python déclare une compatibilité à partir de la 3.8 et embarque httpx, requests, websockets et pydantic en version 2 ou ultérieure.
# the Python client
pip install firecrawl-py
# the JavaScript client, short name or historical name
npm install firecrawl
npm install @mendable/firecrawl-js
# the command line tool, handy for a quick check
npm install -g firecrawl-cli
firecrawl scrape https://example.com
# key read automatically by both SDKs
export FIRECRAWL_API_KEY=fc-your-keyLes deux paquets npm, firecrawl et @mendable/firecrawl-js, sont publiés à la même version et ont un contenu identique. Le code récent utilise le nom court, les guides plus anciens le nom qui porte le préfixe de l'organisation.
Le premier appel en Python ressemble à ceci. Notez les noms de champs : le SDK Python utilise la notation avec underscores, tandis que son homologue JavaScript utilise les mêmes noms écrits en camel case.
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-your-key")
doc = app.scrape(
"https://docs.firecrawl.dev",
formats=["markdown", "links"],
only_main_content=True,
exclude_tags=["nav", "footer", ".cookie-banner"],
wait_for=2000,
timeout=60000,
max_age=3600000,
)
print(doc.markdown[:500])
print(len(doc.links))Le champ max_age indique, en millisecondes, quel âge peut avoir une version d'une page déjà stockée pour être renvoyée sans nouvelle récupération. Le fixer à zéro force une récupération fraîche. Ce seul champ peut réduire à la fois la facture et le temps de réponse dans les tâches qui visitent plusieurs fois les mêmes adresses.
Formats de sortie et données structurées
Le champ formats accepte une liste, donc une seule requête peut renvoyer plusieurs représentations à la fois. Les valeurs disponibles comprennent markdown, html, rawHtml, links, images, screenshot, summary, changeTracking, json et attributes.
Le plus intéressant est json, qui renvoie des données conformes à un schéma au lieu de texte. Vous fournissez le schéma sous forme d'objet JSON Schema ou de modèle Pydantic, ou bien vous décrivez le besoin en une phrase via le champ prompt. Cette commodité a un prix : le format json coûte quatre crédits de plus par page qu'une récupération simple.
from pydantic import BaseModel
from firecrawl import Firecrawl
class Posting(BaseModel):
title: str
company: str
location: str
remote: bool
app = Firecrawl(api_key="fc-your-key")
result = app.scrape(
"https://example.com/jobs/12345",
formats=[{"type": "json", "schema": Posting}],
only_main_content=False,
)
print(result.json["title"], result.json["company"])Pour les pages qui ne révèlent leur contenu qu'après une interaction, il y a le champ actions. Il accepte une liste d'étapes exécutées dans le navigateur avant la lecture du document, et les types disponibles sont wait, click, write, press, scroll, screenshot, executeJavascript, pdf et scrape. Cela couvre les fenêtres modales, les boutons qui déplient du texte et la pagination cachée derrière un contrôle.
La couche de récupération a encore quelques champs qui se révèlent nécessaires en production. Le champ proxy accepte basic, stealth, enhanced et auto, et contrôle la façon dont les requêtes quittent le réseau. Le champ blockAds coupe les scripts publicitaires, removeBase64Images retire les images intégrées à la source, et location avec ses sous-champs country et languages fixe la région depuis laquelle la page doit être vue.
Crawl et maîtrise des coûts
Récupérer un site entier est l'opération qui échappe le plus facilement au contrôle, c'est pourquoi les options de limitation du périmètre doivent figurer dans le premier lancement plutôt qu'après la première facture.
import { Firecrawl } from 'firecrawl'
const app = new Firecrawl({
apiKey: process.env.FIRECRAWL_API_KEY,
maxRetries: 3,
timeoutMs: 120000
})
const job = await app.crawl('https://docs.example.com', {
limit: 500,
maxDiscoveryDepth: 3,
includePaths: ['^/docs/.*'],
excludePaths: ['^/docs/changelog/.*', '^/docs/.*\\.pdf$'],
sitemap: 'include',
crawlEntireDomain: false,
allowSubdomains: false,
ignoreQueryParameters: true,
deduplicateSimilarURLs: true,
delay: 1,
maxConcurrency: 5,
scrapeOptions: {
formats: ['markdown'],
onlyMainContent: true,
blockAds: true
}
})
console.log(job.status, job.completed, '/', job.total, 'credits:', job.creditsUsed)Le champ limit est le seul frein dur et doit toujours être défini. Le champ maxDiscoveryDepth plafonne la profondeur à laquelle de nouvelles adresses peuvent être découvertes, en comptant depuis la page de départ. Les champs includePaths et excludePaths acceptent des expressions régulières appliquées par défaut au chemin plutôt qu'à l'adresse complète, sauf si vous définissez regexOnFullURL.
Le champ sitemap accepte skip, include et only. La valeur only est souvent le meilleur choix pour une documentation, car elle prend les adresses du seul sitemap et saute la découverte par liens, ce qui supprime les descentes accidentelles dans les archives et les filtres.
Les champs delay et maxConcurrency décident de la force avec laquelle vous frappez le serveur de l'autre côté. Martyriser le site de quelqu'un d'autre avec cinquante connexions parallèles est le comportement qui vous place sur une liste de blocage, et parfois dans la boîte de réception d'un service juridique. Firecrawl respecte par défaut les directives de robots.txt, et l'option ignoreRobotsTxt permet de le désactiver. La simple existence de l'interrupteur ne signifie pas que l'utiliser soit approprié, et la documentation du projet note que la responsabilité de respecter les politiques des sites visités incombe à l'utilisateur.
Pour les longues tâches, il existe un objet watcher qui émet des événements portant les documents au fur et à mesure de leur arrivée, au lieu d'imposer une boucle d'interrogation du statut. L'alternative est le champ webhook, qui envoie des notifications à une adresse que vous fournissez.
Firecrawl dans un pipeline RAG
Firecrawl est rarement la dernière pièce du puzzle. Dans un pipeline typique, il récupère le contenu, autre chose le découpe en chunks, et autre chose encore calcule les vecteurs et les stocke.
L'intégration avec LangChain vit dans un paquet séparé, langchain-firecrawl, publié sous MIT. Il fournit FirecrawlLoader avec un champ mode qui accepte scrape, crawl, map, extract et search, plus un jeu complet d'outils d'agent : FirecrawlScrape, FirecrawlCrawl, FirecrawlMap, FirecrawlExtract et FirecrawlSearch.
from langchain_firecrawl import FirecrawlLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
loader = FirecrawlLoader(
url="https://docs.example.com",
mode="crawl",
params={"limit": 200, "scrapeOptions": {"formats": ["markdown"]}},
)
documents = loader.load()
splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=150)
chunks = splitter.split_documents(documents)
print(len(documents), "pages ->", len(chunks), "chunks")Côté LlamaIndex, l'équivalent est FireCrawlWebReader du paquet llama-index-readers-web, qui accepte api_key, un api_url optionnel pour votre propre déploiement et les mêmes modes de fonctionnement. Le paquet exige firecrawl-py en version 4.3.3 ou plus récente.
Si vous construisez un pipeline où certaines sources sont des pages web et d'autres des documents bureautiques et des PDF stockés sur disque, répartir le travail est généralement plus sensé. Firecrawl prend le réseau, tandis que Unstructured décompose les fichiers locaux. Une solution prête à l'emploi avec interface et stockage inclus vient de RAGFlow, que vous pouvez alimenter avec la sortie de Firecrawl au lieu de construire votre propre couche de récupération.
Auto-hébergement : ce que vous obtenez et ce que vous n'obtenez pas
Le projet fournit un fichier docker-compose.yaml et une documentation figée sur une version précise. Arriver à la première récupération réussie prend un quart d'heure, à condition de ne pas essayer de tout activer d'un coup.
git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
git checkout v2.11.162
cat > .env <<'EOF'
USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres
EOF
docker compose up --build -d
# a heartbeat only, it checks neither the queue nor the browser
curl --fail --silent --max-time 5 http://localhost:3002/v0/health/readiness
# the real test: one genuine fetch
curl --fail-with-body --silent --max-time 75 \
-X POST http://localhost:3002/v2/scrape \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com","formats":["markdown"],"timeout":60000}'La pile lance le serveur d'API avec des processus workers, Playwright, Redis, RabbitMQ et PostgreSQL qui joue le rôle de file d'attente. Seul le port 3002 est publié vers l'extérieur par défaut. La variable NUQ_BACKEND fait passer la file sur FoundationDB, et BULL_AUTH_KEY déverrouille le panneau d'administration de la file, mais il vaut mieux laisser les deux tranquilles au premier lancement.
Voici maintenant la partie qu'il vous faut avant de promettre quoi que ce soit à l'équipe. La documentation énonce explicitement ce que la pile par défaut ne prend pas en charge. Les captures d'écran et le champ actions ne fonctionnent pas, car les deux chemins de récupération disponibles signalent l'absence de prise en charge et exigent un service Fire-engine séparé qui n'est pas dans le dépôt. Les capacités agent, browser et interact, ainsi que des formats spécialisés comme product, menu, audio et video, sont réservées au cloud. Les formats appuyés sur un modèle de langage, json compris, exigent de connecter votre propre fournisseur compatible OpenAI ou un Ollama local.
Des questions d'exploitation s'y ajoutent. La configuration par défaut démarre avec l'authentification de l'API désactivée, et le fichier Compose ne définit aucun volume durable pour PostgreSQL, Redis ou RabbitMQ. Cela signifie que les données disparaissent quand un conteneur est remplacé. Exposer un tel déploiement au-delà d'un réseau de confiance sans votre propre couche d'authentification et une terminaison TLS, c'est chercher des ennuis.
L'auto-hébergement a du sens quand vous avez besoin de maîtriser le code ou la destination des données. Il n'a aucun sens comme moyen d'esquiver la facture, car le coût des machines plus le temps de l'équipe sur cette pile dépasse facilement l'abonnement alors que le jeu de fonctionnalités est plus réduit.
Prix du cloud et modèle de crédits
La facturation fonctionne en crédits plutôt qu'en requêtes, donc deux appels avec le même nombre de requêtes peuvent coûter très différemment.
Le forfait gratuit donne mille crédits par mois, deux tâches parallèles, et ne demande aucune carte. Le forfait Hobby coûte 19 dollars par mois ou 16 dollars facturés annuellement, pour cinq mille crédits et cinq tâches parallèles. Le forfait Standard coûte 99 dollars par mois ou 83 dollars annuellement pour cent mille crédits. Le forfait Growth coûte 399 dollars par mois ou 333 dollars annuellement pour cinq cent mille crédits. Le forfait Scale coûte 749 dollars par mois ou 599 dollars annuellement pour un million de crédits, avec un supplément de 397 dollars pour chaque tranche supplémentaire de 350 mille. Le forfait Enterprise est chiffré individuellement.
La conversion en crédits est simple. Récupérer une page, récupérer une page dans un crawl et une vérification de monitor coûtent chacun un crédit par page. Le mapping coûte un crédit par appel. La recherche coûte deux crédits pour dix résultats. Le format json ajoute quatre crédits à chaque page. Une session de navigateur coûte deux crédits par minute. Les requêtes sur l'index d'articles de recherche sont gratuites, et le mode agent est en préversion avec cinq exécutions gratuites par jour et une tarification fondée sur les tokens consommés.
Trois choses valent d'être vérifiées avant de décider. Les crédits ne sont pas reportés au mois suivant sur les forfaits en libre-service ; le report commence à Scale et Enterprise. Il n'existe pas de facturation à l'usage sans abonnement. Les requêtes échouées ne sont pas facturées.
Il y a aussi un écart dans les chiffres de concurrence qu'il vaut mieux éclaircir avant de signer quoi que ce soit. La page des prix indique vingt-cinq requêtes parallèles pour Standard et cinquante pour Growth. La documentation des limites de débit, au même moment, indique cinquante et cent navigateurs simultanés pour ces mêmes forfaits. Pour Free et Hobby, les deux sources concordent, à deux et cinq. Si la concurrence est un paramètre critique pour vous, demandez une confirmation écrite.
Les limites de débit des requêtes fonctionnent séparément. Sur le forfait gratuit, cela fait dix appels scrape, dix appels map, dix appels search et seulement deux appels crawl par minute.
Firecrawl face aux alternatives
| Outil | Modèle de déploiement | Rendu JavaScript | Licence | Étoiles |
|---|---|---|---|---|
| Firecrawl | service cloud ou votre propre pile | oui, navigateur headless | AGPL-3.0 pour le serveur, MIT pour les SDK | environ 170k |
| Crawl4AI | bibliothèque dans votre processus | oui, via Playwright | Apache-2.0 | environ 79k |
| Jina Reader | service derrière un préfixe d'URL | oui, côté service | Apache-2.0 | environ 12k |
| Docling | bibliothèque locale | non, fichiers et documents | MIT | environ 65k |
| Trafilatura | bibliothèque locale | non, HTML uniquement | Apache-2.0 | environ 6,7k |
| Unstructured | bibliothèque ou service | non, fichiers locaux | Apache-2.0 | environ 15k |
Le choix se ramène généralement à deux questions. La première concerne les licences : si l'AGPL est interdite dans votre organisation pour les logiciels qui tournent sur votre propre infrastructure, Crawl4AI sous Apache-2.0 supprime le problème, même si vous exploitez alors vous-même les navigateurs et le travail anti-blocage. La seconde concerne l'échelle : pour une douzaine d'adresses par jour, un script maison sur Playwright suffit et ne demande l'abonnement de personne. Pour des milliers d'adresses par jour sur des domaines différents, maintenir un pool de navigateurs et faire tourner les adresses de sortie coûte à lui seul plus cher que le service.
Erreurs courantes
La première est de supposer que, puisque le SDK est MIT, tout le projet est permissif. Le serveur est sous AGPL-3.0, et c'est ce qui compte dès que vous le déplacez sur votre propre infrastructure. Les couches doivent être séparées et décrites individuellement dans un audit de dépendances.
La deuxième est de lancer crawl sans champ limit. Sans ce frein, la tâche va aussi loin que les liens le permettent, et sur un site avec filtres et pagination le nombre d'adresses peut croître de façon exponentielle. Commencez par map et voyez la taille du site pour un crédit.
La troisième est d'utiliser le format json là où du markdown suffirait. Un écart de coût par page d'un facteur cinq est invisible à dix adresses et très visible à dix mille. Si vous passez de toute façon le texte dans votre propre modèle, extraire les données de votre côté revient souvent moins cher.
La quatrième est de promettre des captures d'écran ou des étapes actions sur un déploiement auto-hébergé. Ces fonctionnalités exigent le service Fire-engine, qui n'est pas dans le dépôt, donc sur la pile par défaut elles ne fonctionneront tout simplement pas.
La cinquième est de confondre les champs max_age et store_in_cache. Le premier dit quel âge peut avoir une version stockée avant de ne plus vous convenir, le second décide si le résultat est stocké du tout. Une tâche destinée à voir les changements d'une page en quelques minutes a besoin d'un max_age bas ou nul, sinon elle reçoit une réponse vieille de plusieurs heures.
La sixième est de traiter le markdown renvoyé comme une entrée prête pour un modèle. Une page de documentation peut atteindre des dizaines de milliers de caractères, ce qui, collé naïvement dans un prompt, mange la fenêtre de contexte et dégrade les résultats. Le découpage en chunks et la recherche vectorielle sont une étape distincte que Firecrawl n'effectue pas.
FAQ
La licence AGPL-3.0 bloque-t-elle l'usage commercial ?
Elle ne le bloque pas, mais elle y attache des conditions. Utiliser le service cloud via un SDK sort du périmètre de cette licence, puisque les SDK sont sous MIT. Faire tourner le serveur vous-même tombe sous l'AGPL, dont la section treize exige de mettre le code source à disposition des utilisateurs qui se connectent par le réseau à une version modifiée. La licence ne comporte pas d'exception pour l'auto-hébergement, donc pour un produit commercial la décision revient à un juriste.
Les SDK Python et JavaScript sont-ils aussi sous AGPL ?
Non. Les répertoires apps/js-sdk et apps/python-sdk portent leurs propres fichiers LICENSE avec du texte MIT. Les métadonnées des paquets sur npm et PyPI déclarent MIT, et l'archive extraite de firecrawl en version 4.34.1 contient bien du texte MIT. Les trois sources concordent ici.
Un déploiement auto-hébergé a-t-il toutes les fonctionnalités du cloud ?
Non. La documentation indique explicitement que les captures d'écran et les étapes actions manquent sans le service Fire-engine, et que les modes agent, browser et interact ne sont pas disponibles. Les formats appuyés sur un modèle de langage exigent de connecter votre propre fournisseur compatible OpenAI ou Ollama.
Combien coûte la récupération de mille pages ?
Mille crédits pour une récupération simple en markdown, ce qui correspond exactement à ce que le forfait gratuit accorde par mois. Ces mêmes mille pages avec le format json reviennent à cinq mille crédits, puisque chaque page coûte un crédit plus quatre pour l'extraction.
Firecrawl respecte-t-il robots.txt ?
Par défaut, oui, et l'option ignoreRobotsTxt dans les réglages du crawl permet de le désactiver. La documentation du projet note que la responsabilité de respecter les politiques des sites visités incombe à l'utilisateur, donc désactiver cette protection est une décision juridique plutôt que technique.
Ai-je besoin de Firecrawl si j'ai déjà Playwright ?
Pour une poignée de sites connus à la structure stable, un script maison est moins cher et donne le plein contrôle. Firecrawl commence à être rentable sur de nombreux domaines différents, où maintenir un pool de navigateurs, faire tourner les adresses de sortie et tenir à jour les règles de nettoyage du contenu devient un projet à part entière.
Le code source et le fichier de licence se trouvent dans le dépôt GitHub, la documentation sur docs.firecrawl.dev, et les tarifs actuels sur la page des forfaits.