Interact après le scraping

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 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()).

1. 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.
2. 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.
3. 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.

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

{  "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}

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.

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

{  "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}

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.

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.

Le langage par défaut. Écrivez directement du code Playwright. page est déjà connectée au navigateur.

Définissez language sur "python" pour l’API Python de Playwright.

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.

Commandes courantes d’agent-browser :

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.

{  "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" />

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" />

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];

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

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 ongletapp.interact(scrape_id, code="await page.click('#tab-2')")# Deuxième appel : l'onglet est toujours sélectionné, extraire son contenuresult = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")print(result.result)

Arrêtez explicitement la session une fois terminé :

Les sessions expirent également automatiquement en fonction du TTL (par défaut : 10 minutes) ou du timeout d'inactivité (par défaut : 5 minutes).

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

1. Créez le scrape avec profile.name et saveChanges: true.
2. Exécutez des interactions par prompt ou par code sur le scrapeId renvoyé.
3. Arrêtez la session pour enregistrer les cookies, le localStorage et les autres données d’état du navigateur.
4. 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.

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

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.

# Session 1 : écrire l'état du navigateur et le sauvegarderRESPONSE=$(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 valeurRESPONSE=$(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.

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

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

Vous avez des retours ou besoin d’aide ? Envoyez un e-mail à help@firecrawl.com ou contactez-nous sur Discord.