Interact | 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. Utilisez Interact lorsque vous avez besoin de :

Scrape derrière un formulaire de connexion — connectez-vous une fois, puis lisez les pages qui n’apparaissent qu’après authentification. See Profils persistants avec Scrape + Interact.
Parcourir la pagination par clics — passez à la page suivante et récupérez chaque ensemble de résultats en réutilisant une seule session. See Interagir par prompt et Cycle de vie d’une session.
Remplir et soumettre un formulaire — saisissez du texte dans les champs et soumettez, depuis un prompt ou depuis du code Playwright. See Interagir par prompt et Exécution de code.
Réutiliser une session authentifiée — enregistrez l’état du navigateur dans un profil nommé et chargez-le lors de scrapes ultérieurs. See Profils persistants avec Scrape + Interact.
Démarrer une session sans scraping préalable — ouvrez un browser autonome que vous pilotez directement. See Browser Sandbox.

Choisissez le bon modèle d’interaction

Besoin	Utiliser	Documentation canonique	Méthodes SDK (Node)
Démarrer une session de navigateur autonome sans scraping préalable	Browser Sandbox / session Interact autonome	Browser Sandbox, Créer une session de navigateur, Exécuter du code du navigateur, Lister les sessions de navigateur, Supprimer une session de navigateur	`browser()`, `browserExecute()`, `listBrowsers()`, `deleteBrowser()`
Continuer à partir d’un résultat de scraping avec `scrapeId`	Interact après le scraping	Exécuter Interact, Arrêter Interact	`interact()`, `stopInteraction()`

Utilisez Interact lié au scraping lorsque le workflow commence par POST /v2/scrape et que la réponse inclut data.metadata.scrapeId. Utilisez Browser Sandbox lorsque vous avez besoin d’une session autonome avec son propre cycle de vie. Le Python SDK utilise les équivalents en snake_case (browser(), browser_execute(), list_browsers(), delete_browser(), interact(), stop_interaction()).

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. Si vous souhaitez conserver l’état du navigateur, transmettez profile dans cette requête.
Interact en appelant POST /v2/scrape/{scrapeId}/interact avec un prompt ou du code playwright. Ne transmettez pas profile ici ; la session d’interaction hérite du profil de la tâche de scraping.
Arrêtez la session avec DELETE /v2/scrape/{scrapeId}/interact lorsque vous avez terminé. Pour les profils inscriptibles, les modifications sont enregistrées à l’arrêt de la session.

Démarrage rapide

Scrapez une page, interagissez avec elle, puis arrêtez la session :

from firecrawl import Firecrawl

app = 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",
)

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

# 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)

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({
  // Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  // apiKey: 'fc-YOUR-API-KEY',
});

// 1. Scraper la page d'accueil d'Amazon
const result = await app.scrape('https://www.amazon.com', { formats: ['markdown'] });
const scrapeId = result.metadata?.scrapeId;

// 2. Interagir — rechercher un produit et obtenir son prix
await app.interact(scrapeId, { prompt: 'Search for iPhone 16 Pro Max' });
const response = await app.interact(scrapeId, { prompt: 'Click on the first result and tell me the price' });
console.log(response.output);

// 3. Arrêter la session
await app.stopInteraction(scrapeId);

# 1. Scraper la page d'accueil d'Amazon
# Aucune API key requise pour démarrer — ajoutez -H "Authorization: Bearer $FIRECRAWL_API_KEY" pour des limites de débit plus élevées :
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.amazon.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# 2. Interagir — rechercher un produit et obtenir son prix
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Search for iPhone 16 Pro Max"}'

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Click on the first result and tell me the price"}'

# 3. Arrêter la session
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# 1. Scrape la page d'accueil d'Amazon (l'ID de scrape est sauvegardé automatiquement)
firecrawl scrape https://www.amazon.com

# 2. Interagir — rechercher un produit et obtenir son prix
firecrawl interact "Search for iPhone 16 Pro Max"
firecrawl interact "Click on the first result and tell me the price"

# 3. Arrêter la session
firecrawl interact stop

Response

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "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)

const response = await app.interact(scrapeId, {
  prompt: 'What are the customer reviews saying about battery life?',
});
console.log(response.output);

# Lancez d'abord un scrape pour obtenir un scrapeId
# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer $FIRECRAWL_API_KEY" pour des limites de débit plus élevées :
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.amazon.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the customer reviews saying about battery life?"
  }'

firecrawl interact "What are the customer reviews saying about battery life?"

La réponse inclut un champ output avec la réponse de l’agent :

Response

{
  "success": true,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "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. Vous pouvez également prendre des captures d’écran pendant la session : utilisez (await page.screenshot()).toString("base64") en Node.js, await page.screenshot(path="/tmp/screenshot.png") en Python, ou agent-browser screenshot en Bash.

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)

const response = await app.interact(scrapeId, {
  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 });
  `,
});
console.log(response.result);

# Lancez d'abord un scrape pour obtenir un scrapeId
# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer $FIRECRAWL_API_KEY" pour des limites de débit plus élevées :
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.click(\"#next-page\"); await page.waitForLoadState(\"networkidle\"); const title = await page.title(); JSON.stringify({ title });",
    "language": "node",
    "timeout": 30
  }'

# Utilise le dernier scrape automatiquement
firecrawl interact -c "
  await page.click('#next-page');
  await page.waitForLoadState('networkidle');
  const title = await page.title();
  const content = await page.\$eval('.article-body', el => el.textContent);
  JSON.stringify({ title, content });
"

# Ou passer un ID de scrape explicitement
# firecrawl interact <scrape-id> -c "await page.title()"

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)

const response = await app.interact(scrapeId, {
  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',
});
console.log(response.stdout);

# Faites d'abord un scrape pour obtenir un scrapeId
# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer $FIRECRAWL_API_KEY" pour des limites de débit plus élevées :
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import json\nawait page.click(\"#load-more\")\nawait page.wait_for_load_state(\"networkidle\")\nitems = await page.query_selector_all(\".item\")\ndata = [await i.text_content() for i in items]\nprint(json.dumps(data))",
    "language": "python"
  }'

firecrawl interact --python -c "
import json
await page.click('#load-more')
await page.wait_for_load_state('networkidle')
items = await page.query_selector_all('.item')
data = [await i.text_content() for i in items]
print(json.dumps(data))
"

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, …), ce qui est 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",
)

// Prendre un instantané pour voir les éléments interactifs
const snapshot = await app.interact(scrapeId, {
  code: 'agent-browser snapshot -i',
  language: 'bash',
});
console.log(snapshot.stdout);
// Output:
// [document]
//   @e1 [input type="text"] "Search..."
//   @e2 [button] "Search"
//   @e3 [link] "About"

// Interagir avec les éléments en utilisant les @refs
await app.interact(scrapeId, {
  code: 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
  language: 'bash',
});

# Lancez d'abord un scrape pour obtenir un scrapeId
# Aucune API key requise pour démarrer — ajoutez -H "Authorization: Bearer $FIRECRAWL_API_KEY" pour des limites de débit plus élevées :
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# Prendre un instantané pour voir les éléments interactifs
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"code": "agent-browser snapshot -i", "language": "bash"}'

# Interagir avec les éléments en utilisant les @refs
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"code": "agent-browser fill @e1 \"firecrawl\" && agent-browser click @e2", "language": "bash"}'

# Prendre un instantané pour voir les éléments interactifs
firecrawl interact --bash -c "agent-browser snapshot -i"

# Interagir avec les éléments en utilisant les @refs
firecrawl interact --bash -c 'agent-browser fill @e1 "firecrawl" && agent-browser click @e2'

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
`screenshot`	Prendre une capture d’écran de la page actuelle
`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,
  "cdpUrl": "wss://browser.firecrawl.dev/...",
  "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" />

URL CDP

Chaque réponse Interact renvoie également un cdpUrl : l’URL WebSocket brute du protocole Chrome DevTools Protocol (CDP) pour la session de navigateur. Utilisez-la pour vous connecter directement à la session en cours depuis Playwright, Puppeteer ou n’importe quel client CDP, et piloter le navigateur avec votre propre code.

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0];

Cycle de vie d’une session

Création

Le premier appel POST /v2/scrape/{scrapeId}/interact poursuit la session d’extraction et démarre l’interaction. La session navigue depuis le même pays que l’extraction : elle utilise le location.country de l’extraction, ou les États-Unis si aucun pays n’a été défini lors de l’extraction. Ne transmettez pas location à interact ; définissez-le dans la requête POST /v2/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)

// Premier appel : cliquer sur un onglet
await app.interact(scrapeId, { code: "await page.click('#tab-2')" });

// Deuxième appel : l'onglet est toujours sélectionné, extraire son contenu
const result = await app.interact(scrapeId, {
  code: "await page.$eval('#tab-2-content', el => el.textContent)",
});
console.log(result.result);

# Premier appel : cliquer sur un onglet
firecrawl interact -c "await page.click('#tab-2')"

# Deuxième appel : l'onglet est toujours sélectionné, extraire son contenu
firecrawl interact -c "await page.\$eval('#tab-2-content', el => el.textContent)"

Nettoyage

Arrêtez explicitement la session une fois terminé :

app.stop_interaction(scrape_id)

await app.stopInteraction(scrapeId);

# SCRAPE_ID est le scrapeId renvoyé par votre appel POST /v2/scrape précédent,
# par exemple : SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')
# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer $FIRECRAWL_API_KEY" pour des limites de débit plus élevées :
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# Arrête la dernière session de scrape
firecrawl interact stop

# Ou arrêter une session spécifique par ID
# firecrawl interact stop <scrape-id>

Les sessions expirent également automatiquement en fonction du TTL (par défaut : 10 minutes) ou du timeout d’inactivité (par défaut : 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. La facturation minimale est d’une minute de browser. Les sessions qui utilisent un prompt sont facturées à 7 credits par minute de browser ; les sessions sans prompt sont facturées à 2. Consultez la Facturation pour plus de détails.

Profils persistants avec Scrape + Interact

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 l’objet profile dans la requête initiale POST /v2/scrape. Ne passez pas profile à POST /v2/scrape/{scrapeId}/interact ; la session interact réutilise la session de navigateur et les paramètres de profil de la tâche de scraping. Arrêtez la session interact avec DELETE /v2/scrape/{scrapeId}/interact afin que les modifications apportées au profil puissent être enregistrées.

cURL

curl -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": {
      "name": "my-profile",
      "saveChanges": true
    }
  }'

curl -X POST "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Click the login button"
  }'

curl -X DELETE "https://api.firecrawl.dev/v2/scrape/SCRAPE_ID/interact" \
  -H "Authorization: Bearer fc-YOUR_API_KEY"

Le cycle de vie du profil est :

Créez le scrape avec profile.name et saveChanges: true.
Exécutez des interactions par prompt ou par code sur le scrapeId renvoyé.
Arrêtez la session pour enregistrer les cookies, le localStorage et les autres données d’état du navigateur.
Démarrez plus tard un scrape avec le même profile.name. Utilisez saveChanges: false lorsque vous voulez uniquement lire l’état existant sans réécrire les modifications.

from firecrawl import Firecrawl

app = 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",
)

# 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.scrape_id

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 en mode lecture seule — déjà connecté
result = app.scrape(
    "https://app.example.com/dashboard",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": False},
)
scrape_id = result.metadata.scrape_id

response = app.interact(scrape_id, prompt="Extract the dashboard data")
print(response.output)
app.stop_interaction(scrape_id)

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({
  // Aucune clé API requise pour démarrer — ajoutez-en une pour des limites de débit plus élevées :
  // apiKey: 'fc-YOUR-API-KEY',
});

// Session 1 : Scrape avec un profil, connexion, puis arrêt (l'état est sauvegardé)
const result1 = await app.scrape('https://app.example.com/login', {
  formats: ['markdown'],
  profile: { name: 'my-app', saveChanges: true },
});
const scrapeId1 = result1.metadata?.scrapeId;

await app.interact(scrapeId1, { prompt: 'Fill in user@example.com and password, then click Login' });
await app.stopInteraction(scrapeId1);

// Session 2 : Scrape avec le même profil en mode lecture seule — déjà connecté
const result2 = await app.scrape('https://app.example.com/dashboard', {
  formats: ['markdown'],
  profile: { name: 'my-app', saveChanges: false },
});
const scrapeId2 = result2.metadata?.scrapeId;

const response = await app.interact(scrapeId2, { prompt: 'Extract the dashboard data' });
console.log(response.output);
await app.stopInteraction(scrapeId2);

# Session 1: Scrape with a profile
# Aucune clé API requise pour démarrer — ajoutez -H "Authorization: Bearer $FIRECRAWL_API_KEY" pour des limites de débit plus élevées :
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/login",
    "formats": ["markdown"],
    "profile": { "name": "my-app", "saveChanges": true }
  }')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

# Log in via interact
curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Fill in user@example.com and password, then click Login"}'

# Arrêt — l'état est sauvegardé dans le profil
curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact"

# Session 2 : Scrape à nouveau avec le même profil en mode lecture seule — déjà connecté
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "formats": ["markdown"],
    "profile": { "name": "my-app", "saveChanges": false }
  }')

SCRAPE_ID=$(echo $RESPONSE | jq -r '.data.metadata.scrapeId')

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Extract the dashboard data"}'

# Session 1 : Scrape avec un profil, connexion, puis arrêt (l'état est sauvegardé)
firecrawl scrape https://app.example.com/login --profile my-app
firecrawl interact "Fill in user@example.com and password, then click Login"
firecrawl interact stop

# Session 2 : Scrape avec le même profil — déjà connecté
firecrawl scrape https://app.example.com/dashboard --profile my-app
firecrawl interact "Extract the dashboard data"
firecrawl interact stop

# Lecture seule : charger l'état du profil sans sauvegarder les modifications
firecrawl scrape https://app.example.com/dashboard --profile my-app --no-save-changes

Paramètre	Par défaut	Description
`name`	None	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, ce qui est 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é.

Vérifier la persistance

Vous pouvez tester la persistance sans dépendre d’une véritable procédure de connexion en écrivant une valeur dans localStorage lors d’une session, en l’arrêtant, puis en lisant cette valeur dans une seconde session avec le même profil.

cURL

# Session 1 : écrire l'état du navigateur et le sauvegarder
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": { "name": "profile-validation", "saveChanges": true }
  }')

SCRAPE_ID=$(echo "$RESPONSE" | jq -r ".data.metadata.scrapeId")

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.evaluate(() => { localStorage.setItem(\"firecrawlProfileCheck\", \"saved\"); document.cookie = \"firecrawl_profile_check=saved; path=/; max-age=3600\"; return localStorage.getItem(\"firecrawlProfileCheck\"); });"
  }'

curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# Session 2 : charger le même profil en mode lecture seule et vérifier la valeur
RESPONSE=$(curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "profile": { "name": "profile-validation", "saveChanges": false }
  }')

SCRAPE_ID=$(echo "$RESPONSE" | jq -r ".data.metadata.scrapeId")

curl -s -X POST "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "await page.evaluate(() => ({ localStorage: localStorage.getItem(\"firecrawlProfileCheck\"), cookie: document.cookie.includes(\"firecrawl_profile_check=saved\") }));"
  }'

curl -s -X DELETE "https://api.firecrawl.dev/v2/scrape/$SCRAPE_ID/interact" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

La deuxième réponse Interact devrait afficher localStorage avec la valeur "saved" et cookie avec la valeur true.

Les profils créés via l’API peuvent ne pas encore apparaître dans Dashboard > Interact > Profiles. Le dashboard ne fournit pas encore un inventaire complet des profils persistants créés via l’API.

Aucune Conservation des Données (ZDR)

Interact prend en charge le mode Aucune Conservation des Données (ZDR) pour les équipes soumises à des exigences strictes en matière de traitement des données. Lorsque ce mode est activé, Firecrawl ne fait persister aucun contenu de page ni aucune sortie d’exécution au-delà de la durée de vie de la session. Pour activer le mode ZDR, définissez zeroDataRetention: true lors de votre premier appel à interact :

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape/YOUR_SCRAPE_ID/interact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "prompt": "Click the pricing tab and summarize the plans",
    "zeroDataRetention": true
  }'

Vous pouvez également passer zeroDataRetention: true lors de la création d’une session autonome avec POST /v2/interact. Toute interaction avec une extraction elle-même effectuée avec zeroDataRetention: true démarre automatiquement une session ZDR. La politique de conservation est enregistrée au niveau de la session : les appels ultérieurs à cette même session restent donc en mode ZDR, même s’ils omettent l’option. ZDR est disponible avec les offres Enterprise et doit être activé pour votre équipe. Les requêtes qui définissent zeroDataRetention: true depuis une équipe pour laquelle ZDR n’est pas activé renvoient une erreur 403. Rendez-vous sur firecrawl.dev/enterprise pour commencer.

Les enregistrements de session et les profils persistants ne sont pas disponibles en mode ZDR. Les requêtes qui combinent zeroDataRetention: true avec recordSession ou profile renvoient une erreur 400.
Une session existante démarrée sans ZDR ne peut pas basculer en mode ZDR. Toute demande de ZDR sur cette session renvoie une erreur 409 : arrêtez la session et démarrez-en une nouvelle avec zeroDataRetention: true.
Les extractions ZDR ne conservent pas l’URL extraite ; il est donc possible que Firecrawl ne puisse pas reconstruire le navigateur à partir de l’extraction d’origine. Si interact renvoie une erreur 409 indiquant que le contexte de relecture n’est pas disponible, passez url dans la requête pour ouvrir cette page dans une nouvelle session ZDR. Les actions de l’extraction d’origine ne sont pas rejouées.

Voir Tarification pour le coût des sessions ZDR.

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 crédits par minute de session
Avec des prompts IA: 7 crédits par minute de session
Extraction: facturée séparément (1 crédit par extraction, plus les coûts spécifiques au format)
Aucune Conservation des Données : les sessions ZDR ajoutent 2 crédits par minute de session ; les sessions en code uniquement sont donc facturées 4 crédits par minute et les sessions avec des prompts IA 9 crédits, avec le même minimum d’une minute. Une extraction ZDR reste soumise à son propre coût ZDR de 1 crédit supplémentaire par page.

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`	Aucune	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`	Aucune	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`	Aucune	Identifiant de l’appelant pour le suivi de l’activité.
`zeroDataRetention`	`boolean`	`false`	Exécute la session en mode Aucune Conservation des Données. Nécessite que la ZDR soit activée pour votre équipe.
`url`	`string`	Aucune	Page à ouvrir dans une nouvelle session lorsque le contexte de l’extraction d’origine n’est plus disponible, par exemple après une extraction en ZDR.

Réponse

Champ	Description
`success`	`true` si l’exécution s’est terminée sans erreur
`cdpUrl`	URL WebSocket brute du Chrome DevTools Protocol (CDP) pour la session de navigateur. Connectez-vous directement avec Playwright, Puppeteer ou n’importe quel client CDP
`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

Démarrages rapides

Guides développeur

Webhooks

Cas d'utilisation

Autres

Contribuer

Interact après le scraping

Choisissez le bon modèle d’interaction

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

URL CDP

Cycle de vie d’une session

Création

Réutilisation

Nettoyage

Profils persistants avec Scrape + Interact

Vérifier la persistance

Aucune Conservation des Données (ZDR)

Quand utiliser chaque option

Tarification

Référence de l’API

Corps de la requête (POST)

Réponse

​Choisissez le bon modèle d’interaction

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

​URL CDP

​Cycle de vie d’une session

​Création

​Réutilisation

​Nettoyage

​Profils persistants avec Scrape + Interact

​Vérifier la persistance

​Aucune Conservation des Données (ZDR)

​Quand utiliser chaque option

​Tarification

​Référence de l’API

​Corps de la requête (POST)

​Réponse

Choisissez le bon modèle d’interaction

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

URL CDP

Cycle de vie d’une session

Création

Réutilisation

Nettoyage

Profils persistants avec Scrape + Interact

Vérifier la persistance

Aucune Conservation des Données (ZDR)

Quand utiliser chaque option

Tarification

Référence de l’API

Corps de la requête (POST)

Réponse