Passer au contenu principal
Scrapez une page pour obtenir des données propres, puis appelez /interact pour commencer à effectuer des actions sur cette page : cliquer sur des boutons, remplir des formulaires, extraire du contenu dynamique ou naviguer plus en profondeur. Décrivez simplement ce que vous voulez faire, ou écrivez du code si vous avez besoin d’un contrôle total.

Prompts IA

Décrivez l’action que vous souhaitez effectuer sur la page

Exécution de code

Interagissez en toute sécurité via l’exécution de code avec playwright, agent-browser

Vue en direct

Observez ou interagissez avec le browser en temps réel via un flux intégrable

​
Comment ça fonctionne

  1. Scrape une URL avec POST /v2/scrape. La réponse inclut un scrapeId dans data.metadata.scrapeId. Vous pouvez éventuellement transmettre un profile pour conserver l’état du navigateur entre les sessions.
  2. Interagissez en appelant POST /v2/scrape/{scrapeId}/interact avec un prompt ou du code playwright. Lors du premier appel, la session de scraping est reprise et vous pouvez commencer à interagir avec la page.
  3. Arrêtez la session avec DELETE /v2/scrape/{scrapeId}/interact lorsque vous avez terminé.

​
Démarrage rapide

Scrapez une page, interagissez avec elle, puis arrêtez la session : 
from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

# 1. Scraper la page d'accueil d'Amazon
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata["scrapeId"]

# 2. Interagir — rechercher un produit et obtenir son prix
app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
response = app.interact(scrape_id, prompt="Click on the first result and tell me the price")
print(response.output)

# 3. Arrêter la session
app.stop_interaction(scrape_id)
Response
{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "The iPhone 16 Pro Max (256GB) is priced at $1,199.00.",
  "exitCode": 0,
  "killed": false
}

​
Interagir par prompt

La manière la plus simple d’interagir avec une page. Décrivez ce que vous voulez en langage naturel, et l’agent cliquera, saisira du texte, fera défiler la page et extraira automatiquement les données. 
response = app.interact(scrape_id, prompt="What are the customer reviews saying about battery life?")
print(response.output)
La réponse inclut un champ output avec la réponse de l’agent :
Response
{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "Customers are generally positive about battery life. Most reviewers report 8-10 hours of use on a single charge. A few noted it drains faster with heavy multitasking.",
  "stdout": "...",
  "result": "...",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

​
Gardez les prompts courts et ciblés

Les prompts sont plus efficaces lorsque chacun correspond à une tâche unique et claire. Au lieu de demander à l’agent d’exécuter un workflow complexe en plusieurs étapes en une seule fois, décomposez-le en appels interact distincts. Chaque appel réutilise la même session de navigateur, de sorte que l’état est conservé d’un appel à l’autre.

​
Exécution de code

Pour un contrôle total, vous pouvez exécuter du code directement dans le sandbox du navigateur. La variable page (un objet Playwright Page) est disponible en Node.js et en Python. Le mode Bash inclut agent-browser en préinstallation.

​
Node.js (Playwright)

Le langage par défaut. Écrivez directement du code Playwright — page est déjà connectée au navigateur. 
response = app.interact(scrape_id, code="""
// Cliquer sur un bouton et attendre la navigation
await page.click('#next-page');
await page.waitForLoadState('networkidle');

// Extraire le contenu de la nouvelle page
const title = await page.title();
const content = await page.$eval('.article-body', el => el.textContent);
JSON.stringify({ title, content });
""")
print(response.result)

​
Python

Définissez language sur "python" pour l’API Python de Playwright. 
response = app.interact(
    scrape_id,
    code="""
import json

await page.click('#load-more')
await page.wait_for_load_state('networkidle')

items = await page.query_selector_all('.item')
data = []
for item in items:
    text = await item.text_content()
    data.append(text.strip())

print(json.dumps(data))
""",
    language="python",
)
print(response.stdout)

​
Bash (agent-browser)

agent-browser est une CLI préinstallée dans le sandbox avec plus de 60 commandes. Elle fournit un arbre d’accessibilité avec des références d’éléments (@e1, @e2, …) — idéal pour l’automatisation pilotée par un LLM. 
# Prendre un instantané pour voir les éléments interactifs
snapshot = app.interact(
    scrape_id,
    code="agent-browser snapshot -i",
    language="bash",
)
print(snapshot.stdout)
# Output :
# [document]
#   @e1 [input type="text"] "Search..."
#   @e2 [button] "Search"
#   @e3 [link] "About"

# Interagir avec les éléments via les @refs
app.interact(
    scrape_id,
    code='agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
    language="bash",
)
Commandes courantes d’agent-browser :
CommandeDescription
snapshotArbre d’accessibilité complet avec références d’éléments
snapshot -iÉléments interactifs uniquement
click @e1Cliquer sur un élément par référence
fill @e1 "text"Effacer le champ et saisir du texte
type @e1 "text"Saisir sans effacer
press EnterAppuyer sur une touche du clavier
scroll down 500Faire défiler vers le bas de 500 pixels
get text @e1obtenir le contenu du texte
get urlobtenir l’URL actuelle
wait @e1Attendre un élément
wait --load networkidleAttendre l’inactivité du réseau
find text "X" clickTrouver un élément par son texte et cliquer
eval "js code"Exécuter du JavaScript dans la page

​
Vue en direct

Chaque réponse interact inclut des URL permettant de visualiser la session de navigateur en temps réel.
FieldDescription
liveViewUrlFlux en lecture seule — à intégrer pour visualiser la session
interactiveLiveViewUrlFlux interactif — les utilisateurs peuvent cliquer, saisir et interagir
<!-- Read-only view -->
<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

<!-- Interactive view — viewers can control the browser -->
<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />
La vue en direct interactive est utile pour créer des interfaces utilisateur destinées aux utilisateurs finaux, où ceux-ci doivent pouvoir voir le navigateur et interagir avec lui — par exemple dans les flux de connexion, la résolution de CAPTCHA ou les workflows guidés.

​
Cycle de vie d’une session

​
Création

Le premier appel POST /v2/scrape/{scrapeId}/interact crée une session de navigateur isolée dans le même état que la page de votre scrape.

​
Réutilisation

Les appels interact suivants sur le même scrapeId réutilisent la session existante. Le navigateur reste ouvert et conserve son état entre les appels, ce qui vous permet d’enchaîner plusieurs interactions : 
# Premier appel — cliquer sur un onglet
app.interact(scrape_id, code="await page.click('#tab-2')")

# Deuxième appel — l'onglet est toujours sélectionné, extraire son contenu
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)

​
Nettoyage

Arrêtez explicitement la session une fois terminé : 
app.stop_interaction(scrape_id)
Les sessions expirent également automatiquement en fonction du TTL (default : 10 minutes) ou du timeout d’inactivité (default : 5 minutes).
Arrêtez toujours les sessions une fois terminé afin d’éviter une facturation inutile. Les credits sont calculés au prorata à la seconde.

​
Profils persistants

Par défaut, chaque session de scrape + interact démarre avec un navigateur propre. Avec profile, vous pouvez enregistrer et réutiliser l’état du navigateur (cookies, localStorage, sessions) entre plusieurs scrapes. C’est utile pour rester connecté et conserver les préférences. Passez le paramètre profile lors de l’appel à scrape. Les sessions portant le même nom de profil partagent le même état. 
from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

# Session 1 : Scrape avec un profil, connexion, puis arrêt (l'état est sauvegardé)
result = app.scrape(
    "https://app.example.com/login",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata["scrapeId"]

app.interact(scrape_id, prompt="Fill in user@example.com and password, then click Login")
app.stop_interaction(scrape_id)

# Session 2 : Scrape avec le même profil — déjà connecté
result = app.scrape(
    "https://app.example.com/dashboard",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata["scrapeId"]

response = app.interact(scrape_id, prompt="Extract the dashboard data")
print(response.output)
app.stop_interaction(scrape_id)
ParamètrePar défautDescription
name—Nom du profil persistant. Les scrapes portant le même nom partagent l’état du navigateur.
saveChangestrueLorsque true, l’état du navigateur est réenregistré dans le profil à l’arrêt de la session interact. Définissez false pour charger des données existantes sans les écrire — utile lorsque vous avez besoin de plusieurs lecteurs concurrents.
Une seule session peut enregistrer dans un profil à la fois. Si une autre session enregistre déjà, vous recevrez une erreur 409. Vous pouvez quand même ouvrir le même profil avec saveChanges: false, ou réessayer plus tard.
L’état du navigateur est enregistré lorsque la session interact est arrêtée. Arrêtez toujours la session une fois terminé afin que le profil puisse être réutilisé.

​
Quand utiliser chaque option

Cas d’usageRecommandéPourquoi
Recherche webRecherchePoint de terminaison de recherche dédié
Obtenir du contenu propre depuis une URLScrapeUn seul appel API, aucune session nécessaire
Cliquer, saisir, naviguer sur une pageInteract (prompt)Décrivez simplement l’action en anglais
Extraire des données nécessitant des interactionsInteract (prompt)Aucun sélecteur nécessaire
Logique de scraping complexeInteract (code)Contrôle total avec Playwright
Interact vs Browser Sandbox : Interact repose sur la même infrastructure que Browser Sandbox, mais offre une meilleure interface pour le cas le plus courant — scraper une page, puis aller plus loin. Browser Sandbox est préférable lorsque vous avez besoin d’une session de navigateur autonome qui n’est pas liée à un scraping spécifique.

​
Tarification

2 credits par minute de session, calculés au prorata à la seconde. Le scrape lui-même est facturé séparément (1 credit par scrape, plus les coûts spécifiques au format).

​
Référence de l’API

​
Corps de la requête (POST)

ChampTypePar défautDescription
promptstring—Tâche en langage naturel pour l’agent d’IA. Obligatoire si code n’est pas défini. Maximum 10 000 caractères.
codestring—Code à exécuter (Node.js, Python ou Bash). Obligatoire si prompt n’est pas défini. Maximum 100 000 caractères.
languagestring"node""node", "python" ou "bash". Utilisé uniquement avec code.
timeoutnumber30timeout en secondes (1–300).
originstring—Identifiant de l’appelant pour le suivi de l’activité.

​
Réponse

ChampDescription
successtrue si l’exécution s’est terminée sans erreur
liveViewUrlURL de la vue en direct en lecture seule pour la session de navigateur
interactiveLiveViewUrlURL de la vue en direct interactive (les utilisateurs peuvent contrôler le navigateur)
outputLa réponse en langage naturel de l’agent à votre prompt. Présent uniquement lors de l’utilisation de prompt.
stdoutSortie standard de l’exécution du code
resultValeur de retour brute du sandbox. Pour code : la dernière expression évaluée. Pour prompt : l’instantané brut de la page utilisé par l’agent pour produire output.
stderrSortie d’erreur standard
exitCodeCode de sortie (0 = succès)
killedtrue si l’exécution a été interrompue en raison d’un timeout
Vous avez des retours ou besoin d’aide ? Envoyez un e-mail à help@firecrawl.com ou contactez-nous sur Discord.