Docs › Guides › Smart Fetch (Auto)

Smart Fetch (Auto)

Vous donnez à FourA une URL et une règle validate pour ce que la vraie page devrait contenir. FourA fait le reste : il parcourt une échelle tenant compte des coûts, s'arrête au premier échelon qui renvoie une response que vos règles acceptent, et mémorise ce qui a fonctionné par hôte pour que le prochain appel sur le même site soit économique.

Ce guide explique ce que fait auto en coulisses, quand l'utiliser, et comment lire sa response. Pour la référence des paramètres, voir API Endpoints.

L'idée

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 le JavaScript. Si vous vous trompez, vous gaspillez des crédits ou vous êtes bloqué.

Auto inverse la situation. Vous déclarez le succès (validate), pas la méthode. FourA grimpe une échelle jusqu'à ce qu'un échelon réussisse :

  1. Cheap probe (single, directement depuis le propre réseau de FourA)
  2. Rotated proxy single
  3. Browser, avec JavaScript et un solveur si le site présente des défis
  4. Browser through proxy pour les cibles les plus difficiles

Auto s'arrête dès qu'un échelon renvoie une response que votre règle validate accepte.

forceProxy prend par défaut la valeur true, donc l'échelon 1 est ignoré et la cible ne voit jamais la propre adresse de FourA. La plupart des appels se terminent alors sur l'échelon 2, 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 l'échelon 1 revient.

Ce que vous envoyez

Le minimum est une URL plus une sous-chaîne validate. Sans validate.data.accept, auto ne peut pas distinguer une vraie page d'un interstitiel de défi renvoyé avec un HTTP 200, et il peut renvoyer le défi 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"]}}
  }'

Options facultatives (voir la référence de l'endpoint pour plus de détails) :

  • returnSession (par défaut true) : retourne le { proxy, cookies, userAgent } gagnant pour que vous puissiez le rejouer.
  • forceProxy (par défaut true) : ignore les échelons de sortie directe. Définissez false uniquement si vous savez que le site est plus favorable à une IP propre qu'aux proxies rotatifs gratuits.
  • timeout_ms (par défaut 120000) : budget total pour l'appel complet. L'échelle le répartit sur les échelons.
  • ignoreProxies : identifiants de proxy à éviter lors de chaque sous-tentative.
  • followRedirects (par défaut 5) : nombre maximum de redirections sur les échelons peu coûteux.

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
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

Trois choses à lire :

  • status et data : la même forme que celle renvoyée par le moteur sous-jacent. status est le statut HTTP de la cible, et non 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 fait, présente sur chaque response. meta.rung nomme l'étape qui a fourni la response, meta.attempts compte les tentatives de sous-appels, meta.solved indique si un défi de bot a été résolu, et meta.credits est la dépense totale pour l'appel (le même nombre que le header X-FourA-Credits).
  • session : le triplet { proxy, cookies, userAgent } qui a forcé la cible. Utilisez-le pour rejouer contre le même hôte via /api/single/ ou /api/browser/.

Auto répond avec un statut HTTP 200 chaque fois que l'échelle s'est exécutée, même lorsque chaque échelon a échoué. Lisez status et error dans le corps pour découvrir ce qui s'est passé, et non le code de statut de transport. Un code différent de 200 de /api/auto/ signifie que FourA a rejeté l'appel avant que l'échelle ne commence : 401 pour une clé invalide, 400 pour un body invalide ou une cible privée, 429 ou 503 pour les rate limits.

Rejouer avec la Session

Une fois que auto renvoie une session, vous pouvez passer directement à 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 lient l'autorisation au magasin de cookies pendant des heures, d'autres effectuent une rotation toutes les quelques minutes. Si une relecture recommence à renvoyer des défis, appelez /api/auto/ une fois de plus pour rafraîchir.

Quand utiliser Auto

Utiliser auto Utiliser single, proxy, ou browser manuellement
Vous ciblez un nouveau site et ne savez pas ce dont il a besoin Vous connaissez déjà le moteur qui fonctionne
Vous voulez un seul appel qui gère pour vous le direct, le proxy et le repli vers le browser Vous voulez un contrôle total sur les tentatives et les délais par appel
Payer quelques secondes de sondage lors du premier appel vous convient La latence du premier appel est plus importante que la découverte
Vous voulez une session apprise que vous pouvez relire à bas coût Vous optimisez une boucle serrée sur une cible connue et fiable

Auto n'est pas toujours le choix le moins cher. 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 dépense, 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 ne peut pas distinguer une vraie page 200 d'un interstitiel de défi 200 déguisé en contenu.

Utilisez validate.data.accept avec une sous-chaîne que seule la vraie page contient:

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

Pour les API JSON, acceptez un nom de champ que vous attendez :

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

Pour les sites qui renvoient légitimement un code différent de 200 (blocages géographiques que vous souhaitez ignorer, 403 intentionnelle sur les 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" et ne détectera pas une page de défi Cloudflare que le WAF renvoie 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 par une request directe peu coûteuse. Le chemin le moins cher.
  • proxy - a nécessité une rotation de proxy pour passer.
  • browser - a nécessité un rendu complet du navigateur, possiblement avec la résolution d'un défi.
  • cache - a rejoué une session chaude issue d'un précédent appel auto. Le chemin le moins cher pour les appels répétés.
  • fail - aucun niveau n'a produit une response acceptée par vos règles.

meta.solved: true signifie qu'un défi anti-bot a été détecté et résolu pendant l'appel. meta.attempts est le nombre de tentatives de sous-appels avant succès. Pour les détails du fournisseur derrière une résolution, lisez le champ defense que les niveaux simples et proxy retournent : voir Défenses anti-bot.

Si un site finit toujours sur browser alors que vous attendiez probe, vérifiez si une règle validate plus stricte (ou moins stricte) permettrait à un niveau moins coûteux de passer. N'oubliez pas que forceProxy a par défaut la valeur true, la sonde direct-egress est donc ignorée sauf si vous la désactivez.

Erreurs et cas particuliers

Quand auto échoue, la response contient status (généralement le statut du dernier niveau ayant échoué) et une chaîne error :

{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status: 0 signifie qu'aucun échelon n'a produit de response (chaque tentative a expiré ou a été rejetée). Un status non nul plus error signifie que la dernière tentative a obtenu une response, mais qu'auto l'a rejetée (validation ou autre).

Vérifiez meta.attempts et meta.credits pour voir où le budget a été dépensé. Si meta.attempts est élevé et que meta.rung est 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 rotatifs en ce moment.

Ce qu'Auto ne fait pas

  • Il ne contourne pas les restrictions légales. Si un site est géo-bloqué et rejette chaque sortie que FourA peut atteindre, auto renvoie le blocage.
  • Il ne met pas le contenu en cache. Chaque appel atteint toujours la cible. La "session chaude" correspond au proxy et aux cookies, et non à la response.
  • Il n'écrit pas dans le Journal d'activité sous forme de ligne distincte des sous-appels. Les sous-appels Single, Proxy ou Browser qu'auto effectue en votre nom apparaissent dans l'activité; l'appel /api/auto/ externe est un coordinateur.

Voir aussi

Mis à jour : 12 août 2026
← Gestion de la protection anti-bot