Smart Fetch (Auto)
Vous transmettez à FourA une URL et une règle validate définissant ce que la vraie page doit contenir. FourA s'occupe du reste: il parcourt une échelle optimisée en fonction des coûts, s'arrête au premier échelon qui renvoie une réponse acceptée par vos règles, et mémorise ce qui a fonctionné par hôte afin que le prochain appel sur le même site soit économique.
Ce guide explique le fonctionnement interne du mode auto, quand l'utiliser et comment lire sa réponse. Pour la référence des paramètres, consultez API Endpoints.
Le concept
La plupart des configurations de scraping vous obligent à choisir le moteur à l'avance. Single est le plus rapide, Proxy ajoute la rotation, Browser gère JavaScript. Si vous faites le mauvais choix, vous gaspillez des crédits ou vous vous faites bloquer.
Le mode auto inverse la logique. Vous déclarez le succès (validate), pas la méthode. FourA gravit une échelle jusqu'à ce qu'un échelon réussisse:
- Sonde économique (single, directement depuis le propre réseau de FourA)
- Browser, directement depuis le propre réseau de FourA, avec JavaScript et un solveur si le site présente un challenge
- Single avec proxy rotatif
- Browser via proxy pour les cibles les plus difficiles
Le mode auto s'arrête dès qu'un échelon renvoie une réponse acceptée par votre règle validate.
Un échelon se situe en dehors de cet ordre. Lorsqu'une sortie atteint le site mais que ce dernier refuse l'URL profonde demandée, le mode auto récupère la page d'accueil du site via cette même sortie, conserve les cookies distribués par la page d'accueil, puis demande à nouveau votre URL en les transmettant. Il s'agit de l'échelon warmup. Il ne s'exécute que sur une URL plus profonde que la racine du site, uniquement après l'échec de la tentative directe, et il ne peut qu'ajouter un résultat positif, jamais en retirer.
forceProxy est défini par défaut sur true, donc les échelons 1 et 2 sont ignorés et la cible ne voit jamais l'adresse propre de FourA. La plupart des appels se terminent alors à l'échelon 3, ou sur une session chaude rejouée. Définissez forceProxy: false lorsque vous savez qu'une cible traite mieux une adresse propre qu'une adresse tournante, et les échelons 1 et 2 seront réactivés.
Ce que vous envoyez
Le strict minimum est une URL et une sous-chaîne validate. Le mode auto reconnaît les pages de challenge courantes de manière autonome, mais sans validate.data.accept, il ne peut pas distinguer une vraie page d'une page de vérification inconnue, ou d'une page chargée sans votre contenu, et il risque de considérer l'une ou l'autre comme un succès.
curl -X POST https://eu.api.foura.ai/api/auto/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/product/42",
"validate": {"data": {"accept": ["Add to cart"]}}
}'
Paramètres optionnels (consultez la référence de l'endpoint pour tous les détails) :
returnSession(par défauttrue) : renvoie le{ proxy, cookies, userAgent }gagnant afin que vous puissiez le rejouer.forceProxy(par défauttrue) : saute les paliers à sortie directe. Définissezfalseuniquement si vous savez que le site est plus tolérant envers une IP propre qu'envers des sorties tournantes.timeout_ms(par défaut120000) : budget total pour l'appel complet. L'échelle le répartit entre les paliers.ignoreProxies: identifiants de proxy à éviter lors de chaque sous-tentative.followRedirects(par défaut5) : nombre maximal de redirections sur les paliers économiques.headers: en-têtes à envoyer au site, sous forme de paires[name, value]. Ils sont transmis sur les requêtes Single et Proxy, y compris lors de la recherche d'une sortie fonctionnelle, et les paliers de navigateur ne les envoient pas. Votre propreCookieparvient au site sans modification, et les cookies d'une session chaude sont ajoutés à côté uniquement sous des noms que vous n'avez pas envoyés. Lorsqu'une session chaude contient unuserAgent, il remplace votreUser-Agent. Les en-têtes conditionnels tels queIf-None-MatchetIf-Modified-Sincesont exclus de la recherche de sortie, sauf si votrevalidate.status.acceptindique304.exitClass:premiumpermet au mode Auto d'escalader vers une sortie premium dès que le pool standard ne parvient pas à atteindre la page ;standardindique de ne jamais escalader. Nécessite un forfait incluant les sorties premium. Consultez exitClass sur Smart Fetch.
Ce que vous recevez en retour
{
"status": 200,
"data": "<!doctype html>...",
"headers": [{"content-type": "text/html"}],
"meta": {
"rung": "cache",
"solved": false,
"attempts": 1,
"credits": 2,
"attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
"browserRequests": 0
},
"session": {
"proxy": "A1B2C3",
"cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
"userAgent": "Mozilla/5.0..."
}
}
Trois éléments à lire :
statusetdata: la réponse de la cible.dataest du texte quel que soit l'échelon qui a servi la page, donc une page JSON arrive sous forme de texte JSON et vous l'analysez vous-même.statusest le statut HTTP de la cible, pas le statut de transport de votre appel vers FourA. Pour les échelons single et proxy,headersest un tableau par saut. Pour les échelons browser,headersest un objet plat.meta: la trace de ce que l'échelle a exécuté, présente sur chaque réponse dès que l'échelle a démarré.meta.rungnomme l'étape qui a délivré la réponse,meta.attemptscompte les tentatives de sous-appels,meta.solvedindique si une page de défi a été complétée, etmeta.creditscorrespond à la dépense totale pour l'appel (le même montant que le headerX-FourA-Credits).meta.attemptsByEngineetmeta.browserRequestsindiquent ce que l'appel a dépensé : voir What a Call Spent. Lorsque la request précisait unexitClass,meta.exitClassindique quelle classe de sortie a délivré le résultat.session: le triplet{ proxy, cookies, userAgent }qui a débloqué la cible. Utilisez-le pour rejouer contre le même hôte via/api/single/ou/api/browser/. Un champ peut être absent : une session obtenue par une simple récupération proxy comporteproxymais aucunuserAgent, et sa listecookiesne contient que les cookies définis par la page de vérification d'un site avant que celui-ci ne serve la page, elle est donc souvent vide. Une réponse issue de la sonde directe économique ne comporte unsessionque si une telle page de vérification a défini des cookies, et elle ne contient alors quecookies. Un statut listé dans votrevalidate.status.acceptqu'une sortie a renvoyé (comme le404d'une page supprimée) n'a aucunsession.
Auto répond avec HTTP 200 dès que l'échelle a été exécutée, même si chaque échelon a échoué. Lisez status et error dans le body pour savoir ce qui s'est passé, et non le code de statut de transport. Une réponse non-200 de /api/auto/ signifie que l'appel n'a jamais atteint l'échelle : 401 pour une mauvaise clé, 400 pour un body qui n'est pas un JSON valide, une cible sur un réseau privé, une cible sur le propre hôte API de FourA, ou une URL contenant un espace non encodé, 403 avec X-FourA-Limit: plan_limit_premium pour exitClass: premium sur un forfait sans sorties premium, et 502, 503 ou 504 lorsque le service n'a pas pu traiter l'appel ou a expiré. Auto ne consomme aucun créneau au niveau de la passerelle, les limites partagées de la plateforme ne refusent donc pas l'appel lui-même : lorsque l'une d'elles refuse un appel effectué par l'échelle, la réponse est HTTP 200 avec status: 429 ou 503 et retryAfter dans le body. Un champ qui échoue à la validation revient également sous forme de HTTP 200, avec status: 400. Une limite de forfait atteinte au sein de l'échelle revient aussi sous forme de HTTP 200, avec le refus dans le body (voir When Your Plan's Limits Meet the Ladder).
Rejouer avec la session
Après le renvoi d'une session par auto, vous pouvez passer directement à Single ou Browser pour les pages suivantes sur le même hôte. Aucune nouvelle ascension de l'échelle, aucune nouvelle sonde.
import requests
API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}
# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
"url": "https://example.com/product/42",
"validate": {"data": {"accept": ["Add to cart"]}},
}).json()
session = r.get("session") or {}
proxy = session.get("proxy")
user_agent = session.get("userAgent")
# 2) Follow-up pages: replay through single with the same proxy, UA and cookies.
for sku in ("43", "44", "45"):
body = {"method": "GET", "url": f"https://example.com/product/{sku}"}
if proxy:
body["proxy"] = proxy
headers = []
if user_agent:
headers.append(["User-Agent", user_agent])
if session.get("cookies"):
headers.append(["Cookie", "; ".join(f"{c['name']}={c['value']}" for c in session["cookies"])])
if headers:
body["headers"] = headers
r = requests.post(f"{API}/api/single/", headers=H, json=body).json()
print(sku, r["status"])
La session n'est durable que dans la mesure où la cible le permet. Certains sites associent l'autorisation au cookie jar pendant des heures; d'autres la renouvellent toutes les quelques minutes. Si un replay recommence à renvoyer des challenges, appelez /api/auto/ une nouvelle fois pour rafraîchir la session.
Quand utiliser Auto
| Utiliser auto | Utiliser manuellement single, proxy ou browser |
|---|---|
| Vous ciblez un nouveau site et ignorez ses prérequis | Vous connaissez déjà le moteur fonctionnel |
| Vous voulez un appel unique gérant le fallback proxy et browser | Vous voulez un contrôle total sur les retries et les timeouts par appel |
| Vous acceptez quelques secondes d'analyse lors du premier appel | La latence du premier appel importe plus que l'exploration |
| Vous voulez une session acquise réutilisable à faible coût | Vous optimisez une boucle rapide sur une cible validée |
Auto n'est pas toujours le choix le plus économique. Si vous savez qu'une cible fonctionne avec single + unblocker, appeler Single directement coûte 2 crédits avec une latence prévisible. Utiliser Auto sur la même cible coûte ce que son escalade consomme, ce qui peut être supérieur si le site requiert une escalade.
Validate définit le succès pour Auto
Le paramètre le plus important est validate. Sans lui, auto rejette uniquement les pages de challenge qu'il identifie, de sorte qu'une page de vérification inconnue ou une structure vide renvoyée avec un code HTTP 200 est considérée comme du contenu valide.
Utilisez validate.data.accept avec une sous-chaîne présente uniquement sur la vraie page:
{
"validate": {
"data": {
"accept": ["sku-42-add-to-cart", "Customer reviews"]
}
}
}
Pour les API JSON, acceptez un nom de champ attendu :
{
"validate": {
"data": { "accept": ["\"products\":["] },
"status": { "accept": [200] }
}
}
Pour les sites qui renvoient légitimement un code non-200 (une restriction géographique que vous souhaitez ignorer, le 404 ou 410 d'une page supprimée), autorisez-les via validate.status.accept :
{
"validate": {
"status": { "accept": [200, 451] }
}
}
Auto renvoie un statut que vous listez dans validate.status.accept dès qu'une sortie le retourne et qu'il satisfait le reste de votre règle. Quatre statuts font exception : 202, 403, 429 et 503. Auto les interprète comme une vérification de l'émetteur par le site, donc une sortie qui en renvoie un n'arrête pas la recherche, et l'escalade continue.
Sans validate, auto se rabat sur "HTTP 200 = succès" pour chaque page qu'il n'identifie pas comme un challenge, il ne détectera donc pas une page de vérification inconnue renvoyée par un site avec un code 200.
Lire meta.rung pour comprendre ce qui s'est passé
meta.rung est le signal de débogage le plus utile. Valeurs :
probe: résolu via une request directe économique. Le chemin le moins coûteux.proxy: a nécessité une rotation de proxy pour aboutir.browser: a nécessité un rendu navigateur complet, éventuellement avec la résolution d'un challenge.cache: a rejoué une session chaude issue d'un appel auto antérieur. Le chemin le moins coûteux pour les appels répétés.warmup: le site a servi sa page d'entrée mais a bloqué l'URL profonde, auto a donc d'abord récupéré la page d'entrée, conservé les cookies distribués et réitéré la demande avec ceux-ci. La session enregistrée à ce niveau n'est pas liée à une seule sortie, les appels suivants atterrissent donc sur les échelons économiques.fail: aucun échelon n'a produit de response acceptée par vos règles.
meta.solved: true indique qu'une page de challenge a été rencontrée et validée durant l'appel. meta.attempts représente le nombre de tentatives de sous-appels avant le succès. Pour obtenir les détails sous-jacents, consultez le champ defense renvoyé par les échelons direct et proxy : voir Vérifications du site.
Si un site aboutit constamment à browser alors que vous attendiez probe, vérifiez si une règle validate plus stricte (ou moins stricte) permettrait de valider un échelon plus économique. N'oubliez pas que forceProxy est défini par défaut sur true, la sonde de sortie directe est donc ignorée sauf si vous la désactivez.
Ressources consommées par un appel
meta.attemptsByEngine comptabilise les requests envoyées par l'appel à chaque moteur, identiques aux requests affichées dans le panneau des tentatives Auto de votre Vue d'ensemble. meta.browserRequests comptabilise celles qui ont consommé un créneau de votre quota quotidien de navigateur.
"meta": {
"rung": "browser",
"solved": true,
"attempts": 7,
"credits": 47,
"attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
"browserRequests": 2
}
| Champ | Type | Description |
|---|---|---|
meta.attemptsByEngine |
object | Requests envoyées à single, proxy et browser. Une request de navigateur refusée par votre forfait est comptabilisée ici, car elle a bien été envoyée. |
meta.browserRequests |
number | Requests de navigateur ayant consommé un slot de votre quota quotidien. Une request de navigateur refusée par votre forfait ne consomme rien. |
meta.attempts compte les étapes du ladder, donc cette valeur n'est pas toujours égale à la somme de meta.attemptsByEngine. Une étape peut envoyer une request Single puis une request Proxy, et une étape dont le navigateur est déjà fermé pour la journée n'envoie rien.
Le cumul de vos consommations pour la journée est transmis dans les headers X-FourA-Browser-Used-Today et X-FourA-Browser-Limit-Per-Day : consultez Response Headers.
Erreurs et cas particuliers
Lorsque auto échoue, la response contient status (généralement le statut du dernier échelon ayant échoué) et une chaîne error :
{
"status": 502,
"error": "could not find a working exit for the target",
"attempts": 7,
"attemptReport": {
"total": 7,
"noResponse": 5,
"defense": 2,
"contentRejected": 0,
"statusRejected": 0,
"other": 0,
"vendors": ["datadome"],
"summary": "7 attempt(s): 5 got no answer from the site; 2 refused by the site (datadome)"
},
"meta": {
"rung": "fail",
"solved": false,
"attempts": 7,
"credits": 47,
"attemptsByEngine": {"single": 0, "proxy": 4, "browser": 3},
"browserRequests": 3
}
}
status est la réponse du site lors de la dernière tentative rejetée par Auto, comme un 403. Lorsqu'aucune tentative n'a obtenu de réponse du site, il s'agit généralement de 502 ou 504, et error indique si aucune sortie fonctionnelle n'a été trouvée ou si le budget de timeout_ms a été épuisé. status: 0 signifie uniquement que le nom d'hôte de la cible n'a pas pu être résolu, et cette réponse ne comporte aucun meta car la cascade n'a jamais démarré.
Auto s'arrête également prématurément lorsque son navigateur rencontre continuellement une vérification qu'il ne peut pas accomplir. Après le refus du navigateur par deux sorties de cette manière et si la recherche d'une sortie dont la récupération simple valide votre règle validate ne donne rien, ou après trois sorties de ce type, l'appel prend fin. status contient la dernière réponse du site et error commence par the browser was refused by, suivi du nom du système de vérification.
Auto s'arrête également lorsque le site lui-même indique que la page n'existe pas. Lorsque deux sorties renvoient le même 404 ou 410 et que vos règles ne l'acceptent pas, l'appel se termine avec ce status, et error commence par the site answered. Si une page supprimée correspond à une réponse souhaitée, indiquez 404 ou 410 dans validate.status.accept: Auto la renvoie alors comme livrée dès qu'une sortie la récupère.
Après quatre appels consécutifs via Auto avec votre clé API qui se terminent sans la page car le site a persisté dans son refus, Auto cesse de solliciter ce site pour votre clé pendant 120 secondes. Tout appel vers ce site durant ce laps de temps répond immédiatement avec status: 503, error: "target temporarily unservable, retry later" et retryAfter en secondes, et ne coûte rien. Ce calcul est effectué par clé API: les autres clés appelant le même site ne sont pas affectées, et tout appel récupérant la page réinitialise le compteur. Un appel avec exitClass: premium n'est pas bloqué par ce mécanisme.
Consultez attemptReport, meta.attemptsByEngine et meta.credits pour voir où le budget a été alloué. Si meta.attempts est élevé et meta.rung est fail après l'étape du navigateur, la cible nécessite peut-être un timeout_ms plus long, une règle validate plus stricte, ou n'est tout simplement pas joignable via des proxys tournants pour le moment.
Pourquoi un appel Auto a échoué
Chaque réponse en échec d'une cascade exécutée comporte un attemptReport. Il comptabilise les requêtes du moteur revenues sans la page, chacune une seule fois, selon la situation rencontrée.
| Champ | Type | Description |
|---|---|---|
total |
integer | Requêtes revenues sans la page. Au maximum la somme de meta.attemptsByEngine, car une requête browser refusée par votre forfait n'a jamais tenté la cible. |
noResponse |
integer | Aucune réponse obtenue du site |
defense |
integer | Le site a refusé la requête : un contrôle anti-bot a été identifié, la page était un challenge, ou le site a répondu 401, 403, 429 ou 503 |
contentRejected |
integer | La page a été récupérée et seule votre règle validate l'a rejetée |
statusRejected |
integer | Le site a répondu avec un statut que votre requête n'accepte pas, comme un 404 pour une page supprimée |
other |
integer | Échec pour une autre raison, telle qu'une erreur serveur |
vendors |
string[] | Fournisseurs de contrôle anti-bot identifiés lors des refus rencontrés par l'appel |
summary |
string | Une phrase construite à partir des compteurs, prête pour vos logs. Elle indique le statut HTTP renvoyé par le site si aucun fournisseur n'a été identifié, et précise si votre quota quotidien de requêtes browser a été épuisé, empêchant l'ouverture d'un navigateur. |
Les champs correspondent au rapport d'un appel Proxy en échec, sans profilesTried. Deux éléments diffèrent. Proxy compte chaque sortie essayée, jusqu'au maxTries défini, et Auto compte ses propres requêtes. Auto lit également la page et son statut, de sorte qu'un refus est comptabilisé sous defense même si aucun fournisseur n'a été identifié. Un décompte sous contentRejected correspond au cas que vous pouvez corriger vous-même : la page a été renvoyée et votre règle ne correspondait pas.
Quand les limites de votre forfait rencontrent l'échelle
Les sous-appels d'Auto sont des requêtes Single, Proxy et Browser ordinaires sous votre clé, de sorte que les limites de votre forfait s'y appliquent. L'échelle lit le code X-FourA-Limit lors d'un refus et traite les deux cas différemment.
Un échelon fermé laisse le reste de l'échelle utilisable. plan_limit_browser_daily (vos requêtes Browser pour la journée sont épuisées) et plan_limit_concurrency (cet endpoint exécute déjà autant de vos requêtes que le forfait ne le permet) ferment un échelon. Auto continue d'utiliser les autres échelons, vous permettant d'obtenir une page dès qu'une sortie tournante ou une session active sert le contenu, et les sorties testées ne sont pas pénalisées pour un refus issu de votre propre forfait. Aucun bannissement n'est appliqué et aucune session n'est abandonnée.
Un compte épuisé interrompt l'échelle. plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature et plan_limit_premium ne peuvent être résolus par un autre échelon, Auto retourne donc immédiatement une réponse au lieu de consommer davantage de vos crédits inutilement. Le refus est renvoyé dans le corps avec le statut du sous-appel et le même champ reason que les endpoints directs :
{
"status": 429,
"error": "Credit limit reached: 300,000 of 300,000 credits used this billing period. Upgrade your plan or wait for the reset.",
"reason": "plan_limit_credits",
"documentation": "https://foura.ai/prices",
"used": 300000,
"hard_stop": 300000,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z",
"meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
L'intégralité du corps de refus du sous-appel est transmise, ainsi que status, attemptReport et meta. Lisez status depuis le corps et non depuis le statut de transport : auto répond toujours HTTP 200 ici, car l'échelle d'escalade s'est exécutée. Un refus plan_limit_feature ou plan_limit_premium arrive de la même manière avec status: 403. Un sous-appel refusé ne consomme rien, donc meta.credits ne compte que les échelons ayant atteint la cible.
Un appel auto peut occuper plusieurs emplacements pendant l'escalade de son échelle, de sorte qu'un lot parallèle d'appels auto atteint un plafond de concurrence avec moins d'appels que prévu. Exécuter des requêtes en parallèle détaille le dimensionnement du lot.
Ce que Auto ne fait pas
- Il ne modifie pas les restrictions légales. Si un site refuse chaque sortie accessible par FourA, auto renvoie ce refus.
- Il ne met pas le contenu en cache. Chaque appel atteint toujours la cible. La « session chaude » correspond au proxy et aux cookies, pas à la réponse.
- Il représente une seule ligne dans le Journal d'activité, sous l'ID de requête reçu, avec la somme des crédits de ses sous-appels. Ouvrez-le et les sous-appels Single / Proxy / Browser effectués par auto en votre nom sont listés comme ses tentatives, chacun avec son propre résultat. Ils sont décomptés de vos limites Single, Proxy et Browser, jamais de votre nombre de requêtes ou de votre taux de réussite.
En lien
- Points de terminaison d'API : Référence complète des paramètres
- Choisir le bon point de terminaison : Quand choisir auto plutôt que single, proxy ou browser
- Résultats des requêtes : Quels résultats sont facturables
- Sites protégés : Ce que FourA fait sur les sites vérifiant l'identité du client
- Vérifications de sites : Le champ
defensederrièremeta.solved - Recettes MCP : Les mêmes modèles sous forme d'appels d'outils MCP
- Limites de taux : Les limites de forfait auxquelles sont comparés les sous-appels de auto