Smart Fetch (Auto)

Du übergibst FourA eine URL und eine validate Regel dafür, was die echte Seite enthalten soll. FourA erledigt den Rest: Es durchläuft eine kostenbewusste Leiter, stoppt bei der ersten Stufe, die eine von deinen Regeln akzeptierte Response zurückgibt, und merkt sich, was pro Host funktioniert hat, damit der nächste Aufruf auf derselben Seite günstig ist.

Dieser Leitfaden erklärt, was auto im Hintergrund macht, wann du es verwenden solltest und wie du seine Response liest. Die Parameterreferenz findest du unter API Endpoints.

Die Idee

Bei den meisten Scraping-Setups musst du die Engine im Voraus auswählen. Single ist am schnellsten, Proxy fügt Rotation hinzu, Browser verarbeitet JavaScript. Rätst du falsch, verschwendest du Credits oder wirst blockiert.

Auto dreht das um. Du deklarierst den Erfolg (validate), nicht die Methode. FourA klettert eine Leiter hinauf, bis eine Stufe erfolgreich ist:

Günstiger Test (Single, direkt aus dem eigenen Netzwerk von FourA)
Rotated Proxy Single
Browser, mit JavaScript und einem Solver, falls die Seite herausfordert
Browser über Proxy für die schwersten Ziele

Auto stoppt, sobald eine Stufe eine Response zurückgibt, die deine validate Regel akzeptiert.

forceProxy ist standardmäßig true, sodass Stufe 1 übersprungen wird und das Ziel nie die eigene Adresse von FourA sieht. Die meisten Aufrufe enden dann auf Stufe 2 oder bei einer wiederholten warmen Session. Setze forceProxy: false, wenn du weißt, dass ein Ziel eine saubere Adresse besser behandelt als eine rotierende, und Stufe 1 kommt zurück.

Was du sendest

Das Minimum ist eine URL plus ein validate Substring. Ohne validate.data.accept kann auto eine echte Seite nicht von einem Challenge-Interstitial unterscheiden, das mit HTTP 200 zurückgegeben wird, und es gibt die Challenge möglicherweise als Erfolg zurück.

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"]}}
  }'

Optionale Parameter (siehe Endpoint-Referenz für alle Details):

returnSession (Standard true): gibt das erfolgreiche { proxy, cookies, userAgent } zurück, damit du es wiederholen kannst.
forceProxy (Standard true): überspringt Direct-Egress-Stufen. Setze false nur, wenn du weißt, dass die Website einer sauberen IP gegenüber freundlicher ist als kostenlosen rotierenden Proxies.
timeout_ms (Standard 120000): Gesamtbudget für den kompletten Aufruf. Die Leiter teilt es auf die Stufen auf.
ignoreProxies: Proxy-IDs, die bei jedem Teilversuch vermieden werden sollen.
followRedirects (Standard 5): maximale Redirects auf den günstigen Stufen.

Was du zurückbekommst

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

Drei Dinge zum Lesen:

status und data: dieselbe Struktur, die die zugrunde liegende Engine zurückgegeben hat. status ist der HTTP-Status des Ziels, nicht der Transport-Status deines Calls an FourA. Für Single- und Proxy-Rungs ist headers ein Per-Hop-Array. Für Browser-Rungs ist headers ein flaches Objekt.
meta: der Trace dessen, was die Ladder ausgeführt hat, vorhanden in jeder Response. meta.rung benennt den Schritt, der die Response geliefert hat, meta.attempts zählt die Versuche von Sub-Calls, meta.solved markiert, ob eine Bot-Challenge gelöst wurde, und meta.credits ist der Gesamtaufwand für den Call (dieselbe Zahl wie im X-FourA-Credits Header).
session: das { proxy, cookies, userAgent } Tripel, das das Ziel geknackt hat. Nutze es für ein Replay gegen denselben Host via /api/single/ oder /api/browser/.

Auto antwortet mit HTTP 200, wann immer die Ladder lief, selbst wenn jeder Rung fehlschlug. Lies status und error im Body, um herauszufinden, was passiert ist, und nicht den Transport-Statuscode. Ein Nicht-200-Status von /api/auto/ bedeutet, dass FourA den Call abgelehnt hat, bevor die Ladder startete: 401 für einen ungültigen Key, 400 für einen fehlerhaften Body oder ein privates Ziel, 429 oder 503 für Rate Limits.

Replay mit der Session

Nachdem Auto eine Session zurückgibt, kannst du für Folgeseiten auf demselben Host direkt zu Single oder Browser wechseln. Kein neuer Ladder-Aufstieg, kein neuer Probe.

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"])

Die Session ist nur so dauerhaft, wie das Ziel es zulässt. Manche Seiten binden die Freigabe stundenlang an den Cookie Jar, andere rotieren alle paar Minuten. Wenn ein Replay wieder Challenges zurückgibt, rufe /api/auto/ erneut auf, um sie zu aktualisieren.

Wann du Auto verwenden solltest

Auto verwenden	Single, Proxy oder Browser manuell verwenden
Du zielst auf eine neue Seite ab und weißt nicht, was sie benötigt	Du kennst bereits die funktionierende Engine
Du möchtest einen Call, der Direct, Proxy und Browser-Fallback für dich übernimmt	Du möchtest volle Kontrolle über Retries und Timeouts pro Call
Es ist für dich in Ordnung, beim ersten Call einige Sekunden für Probing zu opfern	Die Latenz beim ersten Call ist wichtiger als die Discovery
Du möchtest eine erlernte Session, die du günstig als Replay nutzen kannst	Du optimierst einen engen Loop auf einem bekannten, guten Ziel

Auto ist nicht immer die günstigste Wahl. Wenn du weißt, dass ein Ziel mit single + unblocker funktioniert, kostet der direkte Aufruf von Single 2 Credits mit vorhersehbarer Latenz. Auto kostet auf demselben Ziel das, was seine Ladder verbraucht, was mehr sein kann, wenn die Seite eine Eskalation erfordert.

Validate sagt Auto, was "Erfolg" bedeutet

Der wichtigste Parameter ist validate. Ohne ihn kann Auto keine echte 200-Seite von einem als Inhalt getarnten 200-Challenge-Interstitial unterscheiden.

Verwende validate.data.accept mit einem Substring, der nur in der echten Seite enthalten ist:

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

Für JSON APIs, akzeptiere einen Feldnamen, den du erwartest:

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

Für Sites, die berechtigterweise non-200 zurückgeben (Geo-Blocks, die du ignorieren möchtest, absichtliche 403 bei ausgeloggten Endpoints), erlaube sie über validate.status.accept:

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

Ohne validate fällt auto auf "HTTP 200 = Erfolg" zurück und erkennt kein Cloudflare-Challenge-Interstitial, das die WAF mit einer 200 zurückgibt.

`meta.rung` lesen, um zu verstehen, was passiert ist

meta.rung ist das nützlichste Debug-Signal. Werte:

probe, gelöst auf einem günstigen direkten request. Der günstigste Pfad.
proxy, benötigte eine proxy-Rotation zum Durchkommen.
browser, benötigte ein vollständiges Browser-Rendering, möglicherweise mit einem Challenge-Solve.
cache, hat eine warme Sitzung aus einem vorherigen Auto-Aufruf wiederholt. Günstigster Pfad bei wiederholten Aufrufen.
fail, keine Stufe erzeugte eine response, die deine Regeln akzeptierten.

meta.solved: true bedeutet, dass während des Aufrufs eine Bot-Challenge erkannt und gelöst wurde. meta.attempts ist die Anzahl der Sub-Call-Versuche vor dem Erfolg. Für die Anbieterdetails hinter einer Lösung lies das Feld defense, das die Einzel- und proxy-Stufen zurückgeben: siehe Anti-Bot Defenses.

Wenn eine Seite immer bei browser endet, obwohl du probe erwartet hast, prüfe, ob eine strengere validate Regel (oder eine weniger strenge) eine günstigere Stufe passieren lassen würde. Denke daran, dass forceProxy standardmäßig true ist, sodass der Direct-Egress-Probe übersprungen wird, es sei denn, du schaltest ihn aus.

Fehler und Grenzfälle

Wenn auto fehlschlägt, enthält die response status (meist den Status der letzten fehlgeschlagenen Stufe) und einen error String:

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

status: 0 bedeutet, dass keine Stufe eine Antwort geliefert hat (jeder Versuch lief in einen Timeout oder wurde abgelehnt). Ein Wert ungleich null für status plus error bedeutet, dass der letzte Versuch eine Antwort erhielt, aber von auto abgelehnt wurde (durch validate oder anderweitig).

Prüfe meta.attempts und meta.credits, um zu sehen, wohin das Budget geflossen ist. Wenn meta.attempts hoch ist und meta.rung nach der Browser-Stufe fail lautet, benötigt das Ziel möglicherweise einen längeren timeout_ms, eine striktere validate-Regel oder ist derzeit einfach nicht über rotierende Proxys erreichbar.

Was Auto nicht tut

Es umgeht keine rechtlichen Einschränkungen. Wenn eine Seite geogeblockt ist und jeden Ausgang ablehnt, den FourA erreichen kann, gibt auto die Blockierung zurück.
Es speichert keine Inhalte im Cache. Jeder Aufruf erreicht weiterhin das Ziel. Die "warm session" besteht aus Proxy und Cookies, nicht aus der Response.
Es schreibt keinen eigenen Eintrag in das Activity Log getrennt von den Unteraufrufen. Die Single-, Proxy- und Browser-Unteraufrufe, die auto in deinem Auftrag durchführt, erscheinen unter Activity; der äußere /api/auto/-Aufruf ist ein Koordinator.