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 Stufenleiter, stoppt bei der ersten Stufe, die eine von deinen Regeln akzeptierte Response liefert, und merkt sich pro Host, was funktioniert hat, damit der nächste Aufruf auf derselben Website günstig ist.

Diese Anleitung erklärt, was auto unter der Haube tut, wann du es einsetzen solltest und wie du die Response liest. Die Parameter-Referenz findest du unter API Endpoints.

Die Idee

Die meisten Scraping-Setups zwingen dich, die Engine vorab zu wählen. Single ist am schnellsten, Proxy ergänzt Rotation, Browser verarbeitet JavaScript. Liegst du falsch, verschwendest du Credits oder wirst blockiert.

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

Günstiger Probe-Request (Single, direkt aus FourAs eigenem Netzwerk)
Browser, direkt aus FourAs eigenem Netzwerk, mit JavaScript und einem Solver, falls die Website eine Challenge anzeigt
Rotated-Proxy-Single
Browser über Proxy für die schwierigsten Ziele

Auto stoppt, sobald eine Stufe eine Response liefert, die deine validate-Regel akzeptiert.

Eine Stufe liegt außerhalb dieser Reihenfolge. Wenn ein Exit die Website erreicht, die Website aber die angeforderte Deep-URL ablehnt, ruft auto die Einstiegsseite der Website über denselben Exit ab, behält die Cookies der Einstiegsseite und fragt deine URL mit diesen Cookies erneut an. Das ist die warmup-Stufe. Sie läuft nur bei URLs, die tiefer als der Root-Pfad liegen, nur nachdem der direkte Versuch bereits fehlgeschlagen ist, und sie kann ein Ergebnis nur ergänzen, niemals verschlechtern.

forceProxy ist standardmäßig true, sodass die Stufen 1 und 2 übersprungen werden und das Ziel FourAs eigene Adresse nie sieht. Die meisten Aufrufe enden dann auf Stufe 3 oder über eine wiederverwendete warme Session. Setze forceProxy: false, wenn du weißt, dass ein Ziel eine saubere Adresse besser behandelt als eine rotierende, um die Stufen 1 und 2 wieder zu aktivieren.

Was du sendest

Das Minimum ist eine URL plus ein validate-Substring. Auto erkennt gängige Challenge-Seiten selbstständig. Ohne validate.data.accept kann es eine echte Seite jedoch nicht von einer unbekannten Prüfseite oder einer Seite ohne deinen Inhalt unterscheiden und wertet beides eventuell als Erfolg.

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 (vollständige Details findest du in der Endpoint-Referenz):

returnSession (Standard: true): Gibt den erfolgreichen { proxy, cookies, userAgent } zurück, damit du ihn wiederholen kannst.
forceProxy (Standard: true): Überspringt Direct-Egress-Stufen. Setze false nur, wenn du weißt, dass die Website mit einer sauberen IP besser funktioniert als mit kostenlosen rotierenden Proxies.
timeout_ms (Standard: 120000): Gesamtbudget für den gesamten Aufruf. Die Ladder 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 wichtige Elemente:

status und data: die Antwort des Ziels. data ist auf jeder Stufe Text: Eine JSON-Seite wird als JSON-String zurückgegeben, selbst wenn sie von einem Browser ausgeliefert wurde; parse sie also auf deiner Seite. status ist der HTTP-Status des Ziels, nicht der Transportstatus deines Aufrufs an FourA. Für Single- und Proxy-Stufen ist headers ein Array pro Hop. Für Browser-Stufen ist headers ein flaches Objekt.
meta: das Trace-Protokoll der Ladder-Aktionen, das in jeder Antwort vorhanden ist, sobald die Ladder gestartet wurde. meta.rung benennt den Schritt, der die Antwort geliefert hat, meta.attempts zählt die Versuche von Unteraufrufen, meta.solved zeigt an, ob eine Challenge-Seite abgeschlossen wurde, und meta.credits sind die Gesamtkosten des Aufrufs (dieselbe Zahl wie im Header X-FourA-Credits).
session: das { proxy, cookies, userAgent }-Tripel, das das Ziel erfolgreich entsperrt hat. Verwende es, um Anfragen an denselben Host über /api/single/ oder /api/browser/ erneut abzuspielen.

Auto antwortet mit HTTP 200, sobald die Ladder lief, selbst wenn jede Stufe fehlgeschlagen ist. Lies status und error im Body aus, um zu erfahren, was passiert ist, nicht den Transport-Statuscode. Ein Status ungleich 200 von /api/auto/ bedeutet, dass der Aufruf die Ladder nie erreicht hat: 401 für einen ungültigen Key, 400 für einen Body, der kein gültiges JSON ist oder ein Ziel in einem privaten Netzwerk anspricht, und 502, 503 oder 504, wenn der Dienst den Aufruf nicht annehmen konnte oder ein Timeout aufgetreten ist. Auto belegt keinen Slot am Gateway, daher weisen die geteilten Limits der Plattform den Aufruf selbst nicht ab: Wenn ein Limit einen von der Ladder getätigten Aufruf ablehnt, ist die Antwort HTTP 200 mit status: 429 oder 503 und retryAfter im Body. Ein Feld, das die Validierung nicht besteht, wird ebenfalls als HTTP 200 mit status: 400 zurückgegeben. Ein innerhalb der Ladder erreichtes Tariflimit wird ebenfalls als HTTP 200 mit der Ablehnung im Body zurückgegeben (siehe When Your Plan's Limits Meet the Ladder).

Replaying 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-Durchlauf, kein erneuter Test.

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 langlebig, wie das Ziel es zulässt. Manche Websites binden die Clearance stundenlang an das 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 nutzen solltest

Auto nutzen	single, proxy oder browser manuell nutzen
Du zielst auf eine neue Website und weißt nicht, was sie benötigt	Du kennst bereits die Engine, die funktioniert
Du möchtest einen einzigen Call, der Direct-, Proxy- und Browser-Fallback für dich übernimmt	Du willst die volle Kontrolle über Retries und Timeouts pro Call
Es ist in Ordnung für dich, beim ersten Call ein paar Sekunden für das Probing zu investieren	Die Latenz des ersten Calls ist wichtiger als Discovery
Du möchtest eine gelernte Session, die du kostengünstig wiederholen kannst	Du optimierst eine enge Schleife auf einem bekannten 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 bei vorhersehbarer Latenz. Auto auf demselben Ziel kostet so viel, wie die Ladder verbraucht, was mehr sein kann, wenn die Seite eine Eskalation erfordert.

Validate definiert für Auto, was „Erfolg“ bedeutet

Der wichtigste Parameter ist validate. Ohne ihn weist Auto nur die Challenge-Seiten ab, die es erkennt. Eine unbekannte Prüfseite oder ein leeres Shell mit HTTP 200 wird sonst als Inhalt gewertet.

Verwende validate.data.accept mit einem Substring, den nur die echte Seite enthält:

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

Akzeptiere bei JSON-APIs einen Feldnamen, den du erwartest:

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

Für Websites, die berechtigterweise Nicht-200-Statuscodes zurückgeben (eine Länderbeschränkung, die du ignorieren möchtest, ein beabsichtigter 403-Code bei Endpoints für ausgeloggte Nutzer), erlaube sie über validate.status.accept:

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

Ohne validate fällt auto für jede Seite, die nicht als Challenge erkannt wird, auf "HTTP 200 = Erfolg" zurück. Eine unbekannte Prüfseite, die eine Website mit einem 200er-Statuscode ausliefert, wird dadurch nicht abgefangen.

`meta.rung` lesen, um den Ablauf zu verstehen

meta.rung ist das nützlichste Signal zum Debuggen. Werte:

probe: Über einen günstigen direkten Request gelöst. Der kostengünstigste Pfad.
proxy: Proxy-Rotation war erforderlich, um durchzukommen.
browser: Vollständiges Browser-Rendering war erforderlich, eventuell inklusive Challenge-Lösung.
cache: Eine bestehende Session aus einem vorherigen auto-Aufruf wurde wiederverwendet. Günstigster Pfad bei wiederholten Aufrufen.
warmup: Die Website hat die Startseite ausgeliefert, aber die Deep-URL blockiert. Daher hat auto zuerst die Startseite aufgerufen, die erhaltenen Cookies gespeichert und den Request damit wiederholt. Die hier gespeicherte Session ist an keinen festen Exit gebunden, sodass Folgeaufrufe die günstigen Stufen nutzen.
fail: Keine Stufe lieferte eine Response, die deinen Regeln entsprach.

meta.solved: true bedeutet, dass während des Aufrufs eine Challenge-Seite aufgetreten ist und gelöst wurde. meta.attempts ist die Anzahl der Versuche (Sub-Calls) bis zum Erfolg. Details dazu findest du im Feld defense, das von den Single- und Proxy-Stufen zurückgegeben wird: siehe Site checks.

Wenn eine Website immer bei browser endet, obwohl du probe erwartet hast, prüfe, ob eine strengere (oder weniger strenge) validate-Regel eine günstigere Stufe erfolgreich abschließen lässt. Beachte, dass forceProxy standardmäßig true ist. Der Direct-Egress-Test wird also übersprungen, sofern du ihn nicht deaktivierst.

Fehler und Sonderfälle

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

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

status ist die Antwort der Website beim letzten Versuch, den auto abgelehnt hat, wie etwa ein 403. Wenn überhaupt kein Versuch eine Antwort von der Website erhalten hat, ist es meist 502 oder 504, und error gibt an, ob kein funktionierender Exit gefunden wurde oder das timeout_ms-Budget aufgebraucht war. status: 0 bedeutet lediglich, dass der Hostname des Ziels nicht aufgelöst werden konnte, und diese Antwort enthält kein meta, da die Leiter nie gestartet wurde.

Prüfe meta.attempts und meta.credits, um zu sehen, wofür das Budget verwendet wurde. Wenn meta.attempts hoch ist und meta.rung nach der Browser-Stufe fail ist, benötigt das Ziel möglicherweise ein längeres timeout_ms, eine strengere validate-Regel oder ist über rotierende Proxys derzeit einfach nicht erreichbar.

Wenn die Limits deines Tarifs auf die Leiter treffen

Die Unteraufrufe von auto sind reguläre Single-, Proxy- und Browser-Requests unter deinem Key, daher gelten deine Tariflimits für sie. Die Leiter liest den X-FourA-Limit-Code bei einer Ablehnung und behandelt die beiden Arten unterschiedlich.

Eine geschlossene Stufe lässt den Rest der Leiter nutzbar. plan_limit_browser_daily (deine Browser-Requests für den Tag sind aufgebraucht) und plan_limit_concurrency (dieser Endpoint führt bereits so viele deiner Requests aus, wie der Tarif erlaubt) schließen eine Stufe. Auto nutzt weiterhin die anderen Stufen, sodass du weiterhin eine Seite erhältst, sobald ein rotierender Exit oder eine aktive Session den Inhalt liefert, und die versuchten Exits werden nicht für eine Ablehnung verantwortlich gemacht, die von deinem eigenen Tarif stammt. Nichts wird gesperrt und keine Session verworfen.

Ein erschöpftes Konto stoppt die Leiter. plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature und plan_limit_premium können durch keine andere Stufe behoben werden, daher kehrt auto sofort zurück, anstatt weitere deiner Credits zu verbrauchen, um dies festzustellen. Die Ablehnung wird im Body mit dem Status des Unteraufrufs und demselben reason-Feld zurückgegeben, das die direkten Endpoints verwenden:

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

Der gesamte Ablehnungskörper aus dem Sub-Call wird übermittelt, plus status und meta. Lies status aus dem Body und nicht aus dem Transportstatus aus: Auto antwortet hier weiterhin mit HTTP 200, da die Ladder durchlaufen wurde. Eine Ablehnung durch plan_limit_feature oder plan_limit_premium kommt auf demselben Weg mit status: 403 an. Ein abgelehnter Sub-Call verbraucht nichts, daher zählt meta.credits nur die Stufen, die es bis zum Ziel geschafft haben.

Ein Auto-Call kann mehrere Slots belegen, während seine Ladder aufsteigt. Daher erreicht ein paralleler Batch von Auto-Calls das Concurrency-Limit mit weniger Calls als erwartet. Requests parallel ausführen behandelt die Dimensionierung des Batches.

Was Auto nicht tut

Es ändert keine rechtlichen Einschränkungen. Wenn eine Website jeden Exit ablehnt, den FourA erreichen kann, gibt Auto diese Ablehnung zurück.
Es speichert keine Inhalte im Cache. Jeder Call trifft weiterhin das Ziel. Die "warme Session" betrifft den Proxy und die Cookies, nicht die Response.
Es ist eine Zeile im Aktivitätsprotokoll unter der Request-ID, die du erhalten hast, mit der Summe der Credits seiner Sub-Calls. Öffnest du sie, werden die Single-, Proxy- und Browser-Sub-Calls, die Auto in deinem Namen ausgeführt hat, als Versuche mit jeweils eigenem Ergebnis aufgeführt. Sie zählen gegen deine Single-, Proxy- und Browser-Limits, nie gegen deine Request-Anzahl oder Erfolgsquote.