Docs › Guides › Smart Fetch (Auto)

Smart Fetch (Auto)

Vous fournissez à FourA une URL et une règle validate définissant ce que la vraie page doit contenir. FourA fait le reste : il parcourt une échelle optimisée selon les coûts, s'arrête au premier échelon renvoyant 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 interpréter sa réponse. Pour la référence des paramètres, consultez API Endpoints.

Le principe

La plupart des architectures de scraping vous obligent à choisir le moteur en amont. Single est le plus rapide, Proxy ajoute la rotation, Browser gère le JavaScript. Une mauvaise estimation entraîne un gaspillage de crédits ou un blocage.

Le mode auto inverse cette logique. Vous définissez le succès (validate), pas la méthode. FourA monte une échelle jusqu'à ce qu'un échelon réussisse :

  1. Sonde économique (single, directement depuis le propre réseau de FourA)
  2. Browser, directement depuis le propre réseau de FourA, avec JavaScript et un résolveur si le site présente un défi
  3. Single avec proxy rotatif
  4. Browser via proxy pour les cibles les plus strictes

Le mode auto s'arrête dès qu'un échelon renvoie une réponse validée par votre règle validate.

Un échelon se situe en dehors de cet ordre. Lorsqu'une sortie atteint le site mais que celui-ci 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, et redemande 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 sans jamais en supprimer.

forceProxy est défini par défaut sur true, les échelons 1 et 2 sont donc 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 rotative, et les échelons 1 et 2 sont réactivés.

Ce que vous envoyez

Le minimum requis est une URL accompagnée d'une sous-chaîne validate. Le mode auto identifie de lui-même les pages de challenge courantes, 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 risque de renvoyer 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éfaut true) : renvoie le { proxy, cookies, userAgent } gagnant afin que vous puissiez le rejouer.
  • forceProxy (par défaut true) : ignore les échelons à sortie directe. Définissez false uniquement si vous savez que le site est plus tolérant avec une IP propre qu'avec des proxys tournants gratuits.
  • timeout_ms (par défaut 120000) : budget total pour l'ensemble de l'appel. L'échelle le répartit entre les échelons.
  • ignoreProxies : identifiants de proxy à éviter à chaque sous-tentative.
  • followRedirects (par défaut 5) : nombre maximal de redirections sur les échelons économiques.

Ce que vous obtenez en retour

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

Trois éléments à lire :

  • status et data : la réponse de la cible. data est du texte à chaque échelon : une page JSON est renvoyée sous forme de chaîne JSON même lorsqu'un navigateur l'a servie, vous devez donc la parser de votre côté. status est le statut HTTP de la cible, pas le statut de transport de votre appel à FourA. Pour les échelons single et proxy, headers est un tableau par saut. Pour les échelons browser, headers est 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.rung indique l'étape qui a fourni la réponse, meta.attempts compte les tentatives de sous-appels, meta.solved indique si une page de challenge a été complétée, et meta.credits est la dépense totale pour l'appel (le même montant que le header X-FourA-Credits).
  • session : le triplet { proxy, cookies, userAgent } qui a débloqué la cible. Utilisez-le pour rejouer la requête vers le même hôte via /api/single/ ou /api/browser/.

Auto répond avec un code HTTP 200 dès que l'échelle s'est exécutée, même si tous les échelons ont échoué. Lisez status et error dans le corps pour savoir ce qui s'est passé, et non le code d'état de transport. Un code différent de 200 de /api/auto/ signifie que l'appel n'a jamais atteint l'échelle : 401 pour une mauvaise clé, 400 pour un corps qui n'est pas un JSON valide ou une cible sur un réseau privé, et 502, 503 ou 504 lorsque le service n'a pas pu traiter l'appel ou a dépassé le délai imparti. Auto n'occupe aucun slot 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 corps. Un champ qui échoue à la validation revient également en HTTP 200, avec status: 400. Une limite de forfait atteinte au sein de l'échelle renvoie également un code HTTP 200, avec le refus dans le corps (voir When Your Plan's Limits Meet the Ladder).

Rejouer avec la session

Après qu'auto a renvoyé une session, vous pouvez basculer directement vers Single ou Browser pour les pages suivantes sur le même hôte. Pas de nouvelle montée d'échelle, pas de 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["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).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 fois de plus pour actualiser.

Quand utiliser Auto

Utiliser auto Utiliser single, proxy ou browser manuellement
Vous ciblez un nouveau site et ignorez ses exigences Vous connaissez déjà le moteur qui fonctionne
Vous voulez un seul appel gérant direct, proxy et fallback browser Vous voulez un contrôle total sur les retries et les timeouts par appel
Vous acceptez quelques secondes de probing lors du premier appel La latence du premier appel importe plus que la découverte
Vous voulez une session apprise rejouable à faible coût Vous optimisez une boucle serrée sur une cible connue et 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. Auto sur la même cible coûte ce que son échelle consomme, ce qui peut être plus élevé si le site nécessite une escalade.

Validate indique à Auto ce que signifie le « succès »

Le paramètre le plus important est validate. Sans lui, auto rejette uniquement les pages de challenge qu'il reconnaît; ainsi, une page de vérification inconnue ou une coquille vide servie avec un code HTTP 200 sera acceptée comme 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 retournent légitimement un code différent de 200 (une restriction géographique que vous souhaitez ignorer, un 403 intentionnel sur des endpoints déconnectés), autorisez-les via validate.status.accept :

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

Sans validate, auto se rabat sur « HTTP 200 = succès » pour chaque page qu'il ne reconnaît pas comme un challenge, et ne détectera donc pas une page de vérification inconnue renvoyée 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 simple requête directe peu coûteuse. Le chemin le plus économique.
  • proxy : a nécessité une rotation de proxy pour aboutir.
  • browser : a nécessité un rendu de navigateur complet, potentiellement avec la résolution d'un challenge.
  • cache : a rejoué une session chaude issue d'un appel auto précédent. Le chemin le plus économique lors des 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 reçus, puis réessayé avec ceux-ci. La session enregistrée à ce niveau n'est pas liée à une seule sortie, permettant aux requêtes suivantes d'utiliser les niveaux économiques.
  • fail : aucun niveau n'a produit une réponse acceptée par vos règles.

meta.solved: true signifie qu'une page de challenge a été rencontrée et résolue pendant l'appel. meta.attempts correspond au nombre de tentatives de sous-appels avant le succès. Pour obtenir les détails sous-jacents, consultez le champ defense renvoyé par les niveaux single et proxy : voir Vérifications de 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 à un niveau plus économique de passer. 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.

Erreurs et cas particuliers

En cas d'échec d'auto, la réponse contient status (généralement le statut du dernier niveau ayant échoué) ainsi qu'une chaîne error :

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status correspond à la réponse du site lors de la dernière tentative rejetée par auto, comme un 403. Si 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 pas de meta car l'escalier n'a jamais démarré.

Vérifiez meta.attempts et meta.credits pour voir où le budget a été utilisé. Si meta.attempts est élevé et que meta.rung vaut fail après l'échelon browser, la cible peut nécessiter un timeout_ms plus long, une règle validate plus stricte, ou n'est tout simplement pas accessible via des proxies tournants pour le moment.

Lorsque les limites de votre forfait rencontrent l'escalier

Les sous-appels d'Auto sont des requêtes Single, Proxy et Browser ordinaires associées à votre clé, de sorte que les limites de votre forfait s'y appliquent. L'escalier lit le code X-FourA-Limit lors d'un refus et traite les deux types différemment.

Un échelon fermé laisse le reste de l'escalier utilisable. plan_limit_browser_daily (vos requêtes Browser du jour sont épuisées) et plan_limit_concurrency (cet endpoint traite déjà autant de vos requêtes que votre forfait le permet) ferment un échelon. Auto continue d'utiliser les autres échelons, de sorte que vous obtenez toujours une page dès qu'une sortie tournante ou une session chaude fournit le contenu, et les sorties tentées ne sont pas pénalisées pour un refus provenant de votre propre forfait. Rien n'est banni et aucune session n'est perdue.

Un compte épuisé interrompt l'escalier. plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature et plan_limit_premium ne peuvent pas être résolus par un autre échelon, donc auto renvoie immédiatement une réponse au lieu de consommer davantage de vos crédits pour le confirmer. Le refus est retourné dans le body avec le statut du sous-appel et le même champ reason que celui utilisé par les endpoints directs :

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "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 et meta. Lisez status depuis le corps et non depuis le statut de transport : auto répond toujours en HTTP 200 ici, car l'échelle 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 comptabilise que les étapes 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 qu'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 en cache le contenu. Chaque appel interroge directement la cible. La "session chaude" concerne le proxy et les cookies, pas la réponse.
  • Il représente une seule ligne dans le Journal d'activité, sous l'identifiant 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 répertorié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 succès.

Liens associés

Mis à jour : 30 septembre 2026
← Comment votre forfait est mesuré