Interagir | Firecrawl

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

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.
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.
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 :

Commande	Description
`snapshot`	Arbre d’accessibilité complet avec références d’éléments
`snapshot -i`	Éléments interactifs uniquement
`click @e1`	Cliquer 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 Enter`	Appuyer sur une touche du clavier
`scroll down 500`	Faire défiler vers le bas de 500 pixels
`get text @e1`	obtenir le contenu du texte
`get url`	obtenir l’URL actuelle
`wait @e1`	Attendre un élément
`wait --load networkidle`	Attendre l’inactivité du réseau
`find text "X" click`	Trouver 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 renvoie un liveViewUrl que vous pouvez intégrer pour voir le navigateur en temps réel. Utile pour le débogage, les démonstrations ou la création d’interfaces pilotées par le navigateur.

Response

{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "stdout": "",
  "result": "...",
  "exitCode": 0
}

<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

Vue en direct interactive

La réponse inclut également un interactiveLiveViewUrl. Contrairement à la vue en direct standard, qui est en lecture seule, la vue en direct interactive permet aux utilisateurs de cliquer, de saisir du texte et d’interagir directement avec la session du navigateur via le flux intégré. Cela est utile pour créer des interfaces de navigateur destinées aux utilisateurs, par exemple pour des parcours de connexion ou des workflows guidés dans lesquels les utilisateurs finaux doivent contrôler le navigateur.

<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />

Cycle de vie d’une session

Création

Le premier appel POST /v2/scrape/{scrapeId}/interact poursuit la session de scrape et démarre l’interaction.

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ètre	Par défaut	Description
`name`	—	Nom du profil persistant. Les scrapes portant le même nom partagent l’état du navigateur.
`saveChanges`	`true`	Lorsque `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’usage	Recommandé	Pourquoi
Recherche web	Recherche	Point de terminaison de recherche dédié
Obtenir du contenu propre depuis une URL	Scrape	Un seul appel API, aucune session nécessaire
Cliquer, saisir, naviguer sur une page	Interact (prompt)	Décrivez simplement l’action en anglais
Extraire des données nécessitant des interactions	Interact (prompt)	Aucun sélecteur nécessaire
Logique de scraping complexe	Interact (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

Code uniquement (sans prompt) — 2 credits par minute de session
Avec des prompts IA — 7 credits par minute de session
Scrape — facturé séparément (1 credit par scrape, plus les coûts spécifiques au format)

Référence de l’API

Exécuter Interact — POST /v2/scrape/{scrapeId}/interact
Arrêter Interact — DELETE /v2/scrape/{scrapeId}/interact

Corps de la requête (POST)

Champ	Type	Par défaut	Description
`prompt`	`string`	—	Tâche en langage naturel pour l’agent d’IA. Obligatoire si `code` n’est pas défini. Maximum 10 000 caractères.
`code`	`string`	—	Code à exécuter (Node.js, Python ou Bash). Obligatoire si `prompt` n’est pas défini. Maximum 100 000 caractères.
`language`	`string`	`"node"`	`"node"`, `"python"` ou `"bash"`. Utilisé uniquement avec `code`.
`timeout`	`number`	`30`	timeout en secondes (1–300).
`origin`	`string`	—	Identifiant de l’appelant pour le suivi de l’activité.

Réponse

Champ	Description
`success`	`true` si l’exécution s’est terminée sans erreur
`liveViewUrl`	URL de la vue en direct en lecture seule pour la session de navigateur
`interactiveLiveViewUrl`	URL de la vue en direct interactive (les utilisateurs peuvent contrôler le navigateur)
`output`	La réponse en langage naturel de l’agent à votre `prompt`. Présent uniquement lors de l’utilisation de `prompt`.
`stdout`	Sortie standard de l’exécution du code
`result`	Valeur 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`.
`stderr`	Sortie d’erreur standard
`exitCode`	Code de sortie (`0` = succès)
`killed`	`true` 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.

Prise en main

Points de terminaison de base

Plus

Guides pour développeurs

Webhooks

Cas d’utilisation

Dashboard

Contribuer

Interagir après le scraping

Prompts IA

Exécution de code

Vue en direct

Comment ça fonctionne

Démarrage rapide

Interagir par prompt

Gardez les prompts courts et ciblés

Exécution de code

Node.js (Playwright)

Python

Bash (agent-browser)

Vue en direct

Vue en direct interactive

Cycle de vie d’une session

Création

Réutilisation

Nettoyage

Profils persistants

Quand utiliser chaque option

Tarification

Référence de l’API

Corps de la requête (POST)

Réponse

Prise en main

Points de terminaison de base

Plus

Guides pour développeurs

Webhooks

Cas d’utilisation

Dashboard

Contribuer

Prompts IA

Exécution de code

Vue en direct

​Comment ça fonctionne

​Démarrage rapide

​Interagir par prompt

​Gardez les prompts courts et ciblés

​Exécution de code

​Node.js (Playwright)

​Python

​Bash (agent-browser)

​Vue en direct

​Vue en direct interactive

​Cycle de vie d’une session

​Création

​Réutilisation

​Nettoyage

​Profils persistants

​Quand utiliser chaque option

​Tarification

​Référence de l’API

​Corps de la requête (POST)

​Réponse

Comment ça fonctionne

Démarrage rapide

Interagir par prompt

Gardez les prompts courts et ciblés

Exécution de code

Node.js (Playwright)

Python

Bash (agent-browser)

Vue en direct

Vue en direct interactive

Cycle de vie d’une session

Création

Réutilisation

Nettoyage

Profils persistants

Quand utiliser chaque option

Tarification

Référence de l’API

Corps de la requête (POST)

Réponse