API-Endpoints-Referenz

Eine Referenz für alle FourA API-Endpoints mit Request-Parametern und Response-Formaten.

Basis-URL

https://eu.api.foura.ai/api

Authentifizierung

Jeder Request erfordert deinen API-Key im Header X-API-Key:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

Erstelle und verwalte API-Keys im Dashboard. Keys verwenden das Präfix pk_live_.

Response-Header

Responses von /api/* enthalten zwei Korrelations-Header:

Header Value Description
X-FourA-Request-Id UUID Eindeutige ID, die dem Request zugewiesen wird. Wird bei jeder Response zurückgegeben, einschließlich 4xx und 5xx, außer bei einem Body, den FourA überhaupt nicht lesen kann: 400 Invalid JSON in request body und 413 werden abgelehnt, bevor eine ID zugewiesen wird. Protokolliere sie auf deiner Seite.
X-FourA-Credits integer Für diesen Request verbrauchte Credits. Wird bei jeder Response zurückgegeben, die eine Engine erreicht hat, unabhängig von Erfolg oder Misserfolg (die Arbeit wurde in beiden Fällen ausgeführt). Ein Aufruf, den FourA abgelehnt hat, bevor eine Engine ihn ausgeführt hat (ein fehlender oder ungültiger Key, ein Plan- oder Plattform-Limit, eine abgelehnte Ziel- oder Proxy-ID), enthält keinen. Unter Request-Ergebnisse erfährst du, welche Ergebnisse abrechenbar sind.

Dieselbe Request-ID dient als Schlüssel für die Vorschau der Request- und Response-Payloads im Aktivitätsprotokoll des Dashboards (24 Stunden aufbewahrt, die letzten 200 pro Key). So kannst du den genauen Request später nachschlagen und direkt aus der Aktivität im Playground erneut ausführen. Gib sie an, wenn du den Support kontaktierst, damit der Request sekundenschnell gefunden werden kann.

$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...

Siehe Response Headers für die vollständige Liste und Nutzungstipps.

Endpoints

Nutzung dieser Endpoints via MCP? Der @fouradata/mcp Server kapselt alle vier Endpoints als native MCP-Tools (foura_auto, foura_single, foura_proxy, foura_browser) mit denselben Eingabeformaten plus einem offload_large Opt-in für token-effizientes Handling großer Responses. Die Unterschiede: foura_browser hat kein lean-Feld und foura_proxy akzeptiert die exit location-Felder derzeit noch nicht.

FourA bietet vier Request-Endpoints, jeweils optimiert für ein bestimmtes Szenario:

Endpoint Ideal für
POST /auto/ Smart Fetch. Du übergibst eine URL, FourA wählt den günstigsten funktionierenden Pfad (rotierter Proxy oder Browser, plus ein direkter Request mit forceProxy: false) und merkt sich pro Host, was funktioniert.
POST /single/ Schnelle HTTP-Requests, statische Seiten, APIs
POST /proxy/ Geschützte Seiten mit automatischer Proxy-Rotation, optionales Länderscoped Routing
POST /browser/ JavaScript-gerenderte Seiten, SPAs
GET /profiles Der Browser-Profil-Katalog für single und proxy. Öffentlich, kein API-Key erforderlich.

Einen detaillierten Leitfaden zur Auswahl findest du unter Choosing the Right Endpoint und im Smart Fetch guide.

Target-URL-Einschränkungen

Ziele, die zu privaten, Loopback- oder reservierten IP-Bereichen auflösen (RFC 5735, RFC 6598, IPv6-reservierte Blöcke), werden mit einem 400 abgelehnt, bevor der Request FourA verlässt. Nur öffentliche Hostnames und IPs werden weitergeleitet.

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

Ein Ziel auf FourAs eigenem API-Host (eu.api.foura.ai oder api.foura.ai) wird auf allen vier Endpoints ebenfalls mit einem 400 abgewiesen, bevor Daten abgerufen oder abgerechnet werden. Eine URL mit einem Leerzeichen oder Steuerzeichen darin wird bei Single, Proxy und Auto genauso mit einem 400 abgewiesen; kodiere das Leerzeichen als %20 (Browser ruft es so ab wie Chrome). Die einzige Seite dort, die FourA abruft, ist /inspect.

{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }

Smart Fetch (Auto)

POST /api/auto/

Du übergibst eine URL sowie optionale validate-Regeln. FourA durchläuft eine kostenbewusste Eskalationsstufe (rotierender Proxy, dann vollständiger Browser) und stoppt bei der ersten Stufe, die eine Antwort liefert, die deine Regeln akzeptieren. Mit forceProxy: false wird zuerst ein günstiger direkter Test ausgeführt. Bei wiederholten Aufrufen desselben Hosts wird stattdessen eine bestehende Session wiederverwendet, sodass der zweite Abruf günstig ist.

Du musst Retries, Pool-Größen oder Proxy-Zahlen nicht manuell anpassen. FourA lernt sie pro Host.

Request-Body

Parameter Typ Erforderlich Standard Beschreibung
url string Ja - Ziel-URL
method string Nein "GET" HTTP-Methode
headers [string, string][] Nein - An das Ziel zu sendende Header als [name, value]-Paare. Jede Stufe außer einer Browser-Stufe sendet sie. Ein von dir gesendeter Cookie erreicht die Website unverändert, und Cookies einer gespeicherten Session werden nur unter Namen ergänzt, die du nicht gesendet hast. Der userAgent einer gespeicherten Session ersetzt deinen User-Agent. Die Proxy-Stufe lässt bedingte Header wie If-None-Match aus, es sei denn, dein validate.status.accept führt 304 auf.
data any Nein - Request-Body für Nicht-GET-Requests
validate object Nein - Erfolgskriterien, gleiches Format wie validate von Single Request (siehe unten). Gib dem Auto-Modus vor, wie eine echte Seite aussieht, damit er Content von einer Challenge-Seite unterscheiden kann.
returnSession boolean Nein true Enthält die erfolgreiche Session (proxy, cookies, userAgent) in der Response, damit du sie über /api/single/ oder /api/browser/ wiederverwenden kannst.
forceProxy boolean Nein true Immer über einen rotierenden Proxy routen. Setze false, um den günstigeren direkten Pfad zu erlauben, wenn das Ziel dies zulässt (einige Schutzmechanismen reagieren strenger auf Proxy-Traffic).
timeout_ms integer Nein 120000 Gesamtes Zeitbudget für den gesamten Aufruf in Millisekunden. Alle Teilversuche laufen innerhalb dieses Budgets. Min 5000, Max 180000.
ignoreProxies string[] Nein - Proxy-IDs, die bei jedem Teilversuch vermieden werden sollen. Verwende IDs aus vorherigen /api/auto/- oder /api/proxy/-Responses.
followRedirects integer Nein 5 Maximale Anzahl an Redirects, denen auf den günstigen Stufen gefolgt wird. 0 zum Deaktivieren. Max 20.
exitClass string Nein - standard oder premium, wie bei Proxy Request. Mit premium kann der Aufruf auf einen Premium-Exit eskalieren, sobald der Standard-Pool die Seite nicht erreichen kann. Erfordert einen Plan mit Premium-Exits. Siehe exitClass on Smart Fetch.

Response

{
  "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..."
  }
}
Feld Typ Beschreibung
status number HTTP-Status des Ziels.
data string Response-Body als Text, unabhängig von der ausliefernden Stufe. Eine JSON-Seite wird als JSON-Text zurückgegeben, du parst sie also selbst.
headers array oder object Response-Header des Ziels. Single- und Proxy-Stufen liefern ein Array von Hop-spezifischen Header-Objekten zurück; Browser-Stufen liefern ein flaches Objekt.
meta.rung string Welche Stufe der Kette die Response geliefert hat. Mögliche Werte: probe (günstiger direkter Request, nur mit forceProxy: false), proxy (rotierender Proxy), browser (vollständiges Browser-Rendering), cache (wiederverwendete warme Session), warmup (Startseite der Website wurde zuerst geladen und ihre Cookies öffneten die Deep-URL) oder fail (keine Stufe erzeugte eine akzeptierte Response).
meta.solved boolean Gibt an, ob die Seite einen zusätzlichen Schritt erforderte (Challenge-Seite) und dieser während dieses Aufrufs abgeschlossen wurde.
meta.attempts number Vor dem Erfolg durchgeführte Unterversuche.
meta.credits number Für diesen Aufruf verbrauchte Gesamtkredits. Entspricht X-FourA-Credits.
meta.attemptsByEngine object An single, proxy und browser gesendete Requests. Ein Browser-Request, den dein Plan abgelehnt hat, zählt mit, da er gesendet wurde.
meta.browserRequests number Browser-Requests, die einen Slot deines Tageskontingents verbraucht haben. Ein vom Plan abgelehnter Browser-Request verbraucht nichts.
meta.exitClass string Ausliefernde Exit-Klasse, vorhanden wenn im Request exitClass angegeben wurde: premium oder standard. Derselbe Wert wird im X-FourA-Exit-Class Response-Header übertragen.
session.proxy string Codierte ID des Proxys, der die Response geliefert hat. Wiederverwendbar für einen Single- oder Browser-Request. Vorhanden, wenn returnSession gleich true ist.
session.cookies array Cookies zur Wiederverwendung, jeweils mit mindestens name und value. Eine Browser-Stufe gibt den Cookie-Jar des Browsers zurück. Eine Proxy-Stufe oder der direkte Test liefert nur die Cookies zurück, die die Seite geöffnet haben (etwa jene von einer Challenge-Seite), nie alle von der Seite gesetzten Cookies; die Liste kann daher leer sein. Vorhanden, wenn returnSession gleich true ist.
session.userAgent string Beim erfolgreichen Versuch verwendeter User-Agent. Vorhanden, wenn returnSession gleich true ist.
error string Fehlermeldung bei fehlgeschlagenem Aufruf.
attemptReport object Bei fehlgeschlagenem Aufruf: Engine-Requests ohne gelieferte Seite, aufgeschlüsselt nach Ursache. Siehe Smart Fetch.

Beispiel

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

Hinweise

  • Auto fungiert als Koordinator. Es ruft intern Single, Proxy oder Browser auf und leitet deinen API-Key an jeden Sub-Call weiter. Der Auto-Aufruf zählt als ein Request in deinem Activity Log und in deiner Overview, mit der Summe der Credits seiner Sub-Calls. Die Sub-Calls werden darunter als Versuche aufgelistet und zählen nie als eigene Requests.
  • Übergib validate.data.accept mit einem Substring, den nur die echte Seite enthält. Ohne diesen Parameter kann Auto ein echtes 200-Ergebnis nicht von einer Challenge-Zwischenseite unterscheiden, die mit Status 200 zurückgegeben wird.
  • Eine entfernte Seite ist die Antwort der Website, keine Verweigerung. Wenn zwei Exits denselben 404 oder 410 zurückgeben und dein validate ihn nicht akzeptiert, endet der Aufruf mit diesem status sowie einem error, der mit the site answered beginnt. Trage den Status in validate.status.accept ein, und Auto liefert die erste Response mit diesem Status, die den Rest deiner validate besteht. Dasselbe gilt für jeden anderen Status, den du dort auflistest, außer 403, 429, 503 und 202, die Websites ebenfalls zusammen mit einer Challenge-Seite senden.
  • timeout_ms begrenzt den gesamten Aufruf. Ein erster kalter Zugriff auf eine geschützte Website kann mehrere zehn Sekunden dauern. Wiederverwendete warme Sessions sind meist in unter einer Sekunde abgeschlossen.

exitClass bei Smart Fetch

exitClass funktioniert bei Smart Fetch genauso wie bei Proxy Request: als Freigabe, nicht als Anweisung. Auto versucht es zuerst über den Standard-Pool. Wenn der Standard-Pool die Seite nicht erreichen kann und der Request premium angibt, öffnet Auto die Seite in einem Browser über einen Premium-Exit. Die dort aufgebaute Session bedient deine späteren Aufrufe derselben Website, die ebenfalls premium angeben. Aufrufe, die dies nicht angeben, verwenden sie nie.

Das Aufbrauchen des Kontingents ist kein Fehler. Sobald der Premium-Traffic deines Tarifs für den Abrechnungszeitraum aufgebraucht ist, wird der Aufruf im Standard-Pool fortgesetzt und meta.exitClass liefert standard. In einem Tarif ohne Premium-Exits wird ein Aufruf mit exitClass: premium über einen 403 mit X-FourA-Limit: plan_limit_premium abgelehnt, bevor Arbeit anfällt.

Premium-Traffic wird wie beim Proxy Request gemessen. Eine in einem Browser geöffnete Seite lädt mehr als nur die reine Seite selbst, daher verbraucht eine Premium-Smart-Fetch-Seite mehr Premium-Traffic als dieselbe über Proxy Request geladene Seite. Um diesen Verbrauch gering zu halten, lädt eine Premium-Smart-Fetch-Seite keine Bilder, Schriftarten und Mediendateien sowie keine Skripte bekannter Werbe-, Analyse- und Consent-Anbieter.


Single Request

POST /api/single/

Sendet einen HTTP-Request mit realistischen, browserähnlichen Wire-Eigenschaften, ohne einen echten Browser zu starten. Dies ist der schnellste Endpoint.

Request Body

Parameter Typ Erforderlich Standard Beschreibung
method string Ja - HTTP-Methode: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Ja - Ziel-URL. Verwende {ts} an beliebiger Stelle in der URL, um den aktuellen Zeitstempel für Cache-Busting einzufügen.
headers [string, string][] Nein - Benutzerdefinierte Header als [name, value]-Paare
unblocker boolean Nein true Realistische Browser-Header senden (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Standardmäßig aktiviert. Wenn du false setzt, fügt FourA keine Browser-Header hinzu, sondern nur die von dir übergebenen.
timeout_ms number Nein 15000 Gesamter Timeout in ms (max: 120000)
connect_timeout_ms number Nein 5000 Verbindungs-Timeout in ms
accept_timeout_ms number Nein 5000 Accept-Timeout in ms (Wartezeit auf Verbindungsannahme)
server_response_timeout_ms number Nein 15000 Server-Antwort-Timeout in ms (Wartezeit auf das erste Byte)
dns_cache_timeout_sec number Nein 120 DNS-Cache-TTL in Sekunden (max: 240)
followRedirects number Nein disabled Maximale Anzahl an Weiterleitungen (0-20). Weglassen zum Deaktivieren.
tryJsonData boolean Nein false Response-Body nach Möglichkeit als JSON parsen
returnBuffer boolean Nein false Rohen Buffer statt decodierten String zurückgeben
data any Nein - Request-Body (String oder Objekt, automatisch zu JSON serialisiert)
proxy string Nein - Proxy-ID aus einer früheren Response, um denselben Exit-Knoten festzuhalten. Übergib den opaken String unverändert zurück. Eine reine Proxy-Adresse wird mit 400 Invalid proxy format abgelehnt. Manche IDs können nicht festgehalten werden: siehe Pinning an exit.
browser string Nein Chrome Vorzutäuschender Browser: Chrome, Edge, Safari, Firefox oder Tor. Siehe Browser profiles.
os string Nein - Vorzutäuschendes Betriebssystem: Windows, macOS, Android oder iOS. Ein Familienname akzeptiert jede seiner Versionen.
version string Nein newest Vorzutäuschende Browser-Version laut Katalog. Bei mehreren Treffern gewinnt die neueste Version.
profile string Nein - Exakte Profil-ID aus GET /api/profiles anstelle der drei obigen Felder.
validate object Nein - Validierungsregeln für Antworten (siehe unten)

Browser-Profile

Standardmäßig verwendet ein Request das neueste Google Chrome. Manche Ziele akzeptieren einen bestimmten Browser und blockieren andere. Daher grenzen browser, os und version einen Katalog vermessener Profile ein, und profile wählt ein Profil direkt per ID aus.

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

Regeln:

  • Die Auswahl erfordert unblocker (standardmäßig aktiviert). Wenn unblocker deaktiviert ist, werden keine Browser-Header gesendet, sodass der Request abgelehnt wird, anstatt ihn nur teilweise anzuwenden.
  • Wenn mehrere Profile übereinstimmen, gewinnt die neueste Version.
  • Eine Kombination, die der Katalog nicht bereitstellen kann, gibt einen Fehler zurück, der die verfügbaren Optionen nennt. Eine unbekannte profile-ID gibt unknown profile '<id>' zurück. Der Request wird niemals als anderer Browser gesendet.
  • Dieselben vier Felder sind im request-Objekt von POST /proxy/ verfügbar.

GET /api/profiles gibt den vollständigen Katalog zurück und benötigt keinen API-Key:

{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}

osFamily ist der Wert zum Filtern beim Erstellen einer Auswahlliste; os behält den Release-Namen für die Anzeige bei.

Validierungsregeln

Mit dem Objekt validate kannst du Bedingungen für Erfolg und Fehlschlag definieren. Wenn eine fail-Bedingung zutrifft, wird der Request als fehlgeschlagen behandelt. Wenn accept-Bedingungen festgelegt sind, werden nur übereinstimmende Responses als erfolgreich behandelt.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Feld Typ Beschreibung
validate.status.accept number[] Zu akzeptierende HTTP-Statuscodes
validate.status.fail number[] Abzulehnende HTTP-Statuscodes
validate.headers.accept object Die Response ist erfolgreich, wenn mindestens ein Paar bei einem beliebigen Redirect-Hop übereinstimmt. Namen und Werte werden unabhängig von Groß- und Kleinschreibung als Teilstring abgeglichen.
validate.headers.fail object Header-Schlüssel-Wert-Paare, die einen Fehler auslösen
validate.data.accept string[] Die Response ist erfolgreich, wenn der Body mindestens einen dieser Strings enthält
validate.data.fail string[] Strings im Response-Body, die einen Fehler auslösen

Beispiel

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'

Response:

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}

Führt das Ziel vor der Auslieferung des Body einen Bot-Check durch, enthält die Response zusätzlich ein defense-Objekt mit Angaben zum Anbieter und dazu, ob der Check bestanden wurde:

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
Feld Typ Beschreibung
status number HTTP-Statuscode des Ziels
headers array Ein Objekt pro Redirect-Hop. Jedes enthält ein Feld result mit der Statuszeile und allen Response-Headern. Multi-Value-Header (Set-Cookie, Link, WWW-Authenticate) werden als String-Arrays zurückgegeben.
data string/object Response-Body (JSON, falls tryJsonData true ist)
total_time number Gesamte Request-Dauer in Sekunden
proxy string Enkodierte ID des verwendeten Proxys (nur wenn proxy im Request übergeben wurde). Verwende sie bei Folgeaufrufen erneut, um denselben Exit-Knoten festzuhalten.
defense object Vorhanden, wenn das Ziel bei diesem Request eine Bot-Prüfung durchgeführt hat oder wenn ein Retry mit den Cookies der Website den Body geliefert hat. defense.solved gibt an, ob eine Prüfung bestanden wurde, defense.retry gibt an, ob ein Retry den Inhalt geliefert hat. Siehe Site checks für alle Felder und die vollständige Liste der Systeme.
error string Fehlermeldung, falls der Request fehlgeschlagen ist

Proxy Request

POST /api/proxy/

Leitet deinen Request über rotierende Proxys mit automatischem Retry bei Fehlern weiter. Optional kannst du die Auswahl auf bestimmte, für das Ziel sichtbare Exit-Länder einschränken.

Request-Body

Parameter Typ Erforderlich Standard Beschreibung
request object Ja - Ein einzelner Request-Body (gleiche Felder wie bei Single Request oben)
timeout_ms number Nein 45000 Gesamtes Timeout fuer alle Versuche in ms (max: 120000)
maxTries number Nein 5 FourA startet keine neuen Versuche mehr, sobald so viele fehlgeschlagen sind (max: 90). Versuche laufen parallel, daher koennen etwas mehr als diese Anzahl abschliessen.
ignoreProxies string[] Nein - Proxy-IDs, die von der Rotation ausgeschlossen werden sollen (nutze IDs aus frueheren Responses)
exitCountries string[] Nein - Strikte Allowlist aus zweistelligen, fuer das Ziel sichtbaren Laendercodes (z. B. ["CZ", "GB"]). Werte werden getrimmt, in Grossbuchstaben umgewandelt und dedupliziert. Exits im Standard-Pool mit unbekanntem Land werden ausgeschlossen, und der Standard-Pool faellt nie auf ein nicht angefordertes Land zurueck. Ein Premium-Exit erfolgt ebenfalls ueber eines der aufgefuehrten Laender.
exitClass string Nein - standard oder premium. premium erlaubt die Eskalation des Requests auf einen Premium-Exit, wenn der Standard-Pool bei einem geschuetzten Ziel Probleme hat. Erfordert einen Plan mit Premium-Exits.
exitState string Nein - Region, aus der der Exit erfolgt. Erfordert exitClass: premium und genau ein Land in exitCountries. Siehe Exit location.
exitCity string Nein - Stadt, aus der der Exit erfolgt. Erfordert exitClass: premium und genau ein Land in exitCountries.
exitAsn string Nein - Netzwerk, aus dem der Exit erfolgt, nach AS-Nummer, zum Beispiel 8866. Erfordert exitClass: premium und genau ein Land in exitCountries.
exitOs string Nein - windows, android, ios oder mac: der Geraetetyp, zu dem die Adresse gehoert. Erfordert exitClass: premium.
exitLifetimeMin integer Nein - Minuten, die der Exit seine Adresse behaelt, 3 bis 1440. Erfordert exitClass: premium.

exitCountries Scoping

Die Auswahl nutzt die neuesten verfuegbaren, fuer das Ziel sichtbaren Laender-Metadaten, die normalerweise innerhalb von etwa zehn Minuten aktualisiert werden. Es handelt sich nicht um einen Live-Geolocations-Lookup waehrend des Requests. Leite das bereitstellende Land nicht aus der Proxy-Host-Adresse ab.

Wenn der aktuelle Pool keine Uebereinstimmung fuer die angeforderten Laender hat und der Request exitClass: premium nicht angegeben hat, gibt die Response HTTP 200 mit einem Error-Envelope zurueck:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

Behalte den angeforderten Scope bei und versuche es später erneut. Ändere oder erweitere ihn nur, wenn sich die Länderanforderung deines Workflows explizit ändert.

Beispiel

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'

Response:

{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}
Feld Typ Beschreibung
proxy string Codierter Bezeichner des verwendeten Proxys. Verwende ihn bei einem Single- oder Browser-Request wieder, indem du ihn als proxy-Feld übergibst, oder überspringe ihn beim nächsten Proxy-Request via ignoreProxies.
exitCountry string Zwei-Buchstaben-Ländercode (zielseitig sichtbar) des Proxys, der den Request verarbeitet hat. Nur vorhanden, wenn der Request exitCountries gesetzt hat, unabhängig von der bedienenden Exit-Klasse. Prüfe vor Weiterverarbeitung der Antwort immer, ob es sich um einen der von dir angeforderten Codes handelt.
exitClass string Gibt an, welche Exit-Klasse diesen Request bedient hat; vorhanden bei einer erfolgreichen Antwort, wenn der Request eine bestimmte Klasse vorgegeben hat. premium bedeutet, dass ein Premium-Exit den Body zurückgegeben hat; standard bedeutet, dass der Standard-Pool verwendet wurde. Ein fehlgeschlagener Aufruf hat nichts ausgeliefert und enthält daher kein exitClass; prüfe stattdessen attemptReport, um Details zu den Versuchen zu sehen.
total number Gesamtlaufzeit nach Echtzeit in Sekunden (Float). Umfasst Proxy-Auswahl, Retries und den erfolgreichen Versuch. total_time misst nur den inneren Request; total ist immer >= total_time.
profile string Das von der Rotation gewählte Browser-Profil, nur vorhanden, wenn es nicht dem von dir angeforderten Profil entspricht. Fehlt der Wert, wurde der Request exakt wie angegeben gesendet. Übergib die ID bei Folgeaufrufen als profile, um den funktionierenden Browser beizubehalten.
error string Fehlermeldung, falls der Request fehlgeschlagen ist. Bei einem Scope-Miss lautet code no_eligible_proxy und details.exitCountries gibt den normalisierten Scope zurück.
attemptReport object Vorhanden bei jedem fehlgeschlagenen Proxy-Aufruf. Zählt die aufgetretenen Ereignisse der Versuche, damit ein blockierter Pool, ein toter Pool und eine validate-Regel ohne Treffer nicht alle denselben Fehler anzeigen. Siehe unten.
request object Vorhanden bei einem fehlgeschlagenen Proxy-Aufruf: Der von FourA ausgeführte Request, inklusive Standardwerten und deinen übergebenen ignoreProxies.

Alle Response-Felder von Single Request sind ebenfalls enthalten, darunter defense: Ein Proxy-Versuch, der auf eine Bot-Erkennung trifft, meldet dies genauso wie Single.

Warum ein Proxy-Aufruf fehlgeschlagen ist

Download maxTry limit reached liefert unabhängig vom Ablauf der Versuche das gleiche Ergebnis, daher enthält jede fehlgeschlagene Proxy-Antwort neben dem Fehler ein attemptReport:

{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
Feld Typ Beschreibung
total integer Durchgeführte Versuche
noResponse integer Der Exit hat nie geantwortet, die Website wurde also nie erreicht
defense integer Die Website hat geantwortet und in der Antwort wurde ein Bot-Check erkannt
contentRejected integer HTTP 200, kein Bot-Check, nur durch dein validate.data abgelehnt
statusRejected integer Die Website hat geantwortet, kein Bot-Check, abgelehnt durch dein validate.status
other integer Geantwortet und keines der obigen Kriterien
vendors string[] Bot-Check-Anbieter, die im Task erkannt wurden
profilesTried string[] Vom Task gesendete Browser-Profile in der Reihenfolge der Erstverwendung. default bedeutet, dass dein Request unverändert gesendet wurde.
summary string Ein aus den Zählern erstellter Satz, sicher für Logs

Der error-String bleibt unverändert, sodass Clients, die darauf matchen, weiter funktionieren. Was bei jedem Zähler zu tun ist: Warum ein Proxy-Request keine Versuche mehr hatte.

exitClass

Manche Ziele blockieren die Exits im Standard-Pool unabhängig von der Anzahl der Versuche. exitClass: premium teilt Proxy mit, dass ein solcher Request zusätzlich zum Standard-Pool an einen Premium-Exit eskaliert werden darf, anstatt nur innerhalb des Pools zu rotieren.

{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}

Drei Dinge solltest du vor dem Senden wissen.

Es ist ein Kontingent, keine feste Anweisung. Der Standard-Pool konkurriert weiterhin um die Antwort und gewinnt meist. Ein Premium-Exit schaltet sich erst ein, wenn der Pool ein kurzes Budget fuer den Request aufgebraucht hat oder das Ziel ihn sichtbar abgewiesen hat. Ein Request, den der Standard-Pool beantwortet, bevor ein Premium-Exit versucht wurde, gilt als normaler Erfolg und kostet dich keinen Premium-Traffic. Sobald ein Premium-Exit versucht wurde, zaehlt dessen Traffic, wie unten beschrieben.

Ein Premium-Exit bleibt innerhalb von exitCountries. Bei einer Laenderliste erfolgt der Premium-Exit ueber eines dieser Laender, und exitCountry in der Response gibt dieses an, genau wie beim Standard-Pool.

Die Response zeigt dir, was die Anfrage tatsaechlich bedient hat. Wenn du eine Klasse angibst, enthaelt die Response exitClass:

{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}

premium bedeutet, dass ein Premium-Exit den Body zurückgegeben hat. standard bedeutet, dass dies der Standard-Pool getan hat. Diese Antwort erhältst du auch, wenn kein Premium-Exit bezogen werden konnte oder wenn der in deinem Tarif enthaltene Premium-Traffic (plus dazugekaufte Kontingente) für den Abrechnungszeitraum aufgebraucht ist. Beides ist kein Fehler, und du kannst deinen Premium-Traffic anhand dieser Werte pro Request statt über eine Monatsgesamtsumme abgleichen. Derselbe Wert wird im X-FourA-Exit-Class-Response-Header übertragen (siehe Response Headers).

Premium-Traffic wird auf Netzwerkebene gemessen. Ein Premium-Versuch zählt alle gesendeten und empfangenen Daten bei der Übertragung über das Netzwerk, komprimiert und verschlüsselt wie übertragen, unabhängig davon, ob deine Seite zurückgegeben wurde. Ein Versuch, der noch lief, als ein anderer Exit geantwortet hat, wird sofort abgebrochen, und der bis dahin übertragene Traffic zählt ebenfalls. Premium-Traffic wird auf dein Premium-Kontingent angerechnet und ist gleichzeitig in deiner Gesamtbandbreite enthalten: dieselben Bytes, doppelt ausgewiesen, aber niemals addiert. Wenn ein Premium-Exit die Seite ausgeliefert hat, entspricht dessen Traffic dem gesamten Traffic des Requests, sodass die Seite nicht noch einmal als Standard-Traffic gezählt wird. Deine Usage & Limits-Seite zeigt den Gesamttraffic, den Premium-Anteil daran und das Premium-Kontingent, an dem du gemessen wirst.

Lässt du das Feld weg oder sendest standard, verbleibt der Request im Standard-Pool: Nur premium erlaubt einen Premium-Exit. Ein erfolgreicher Request, der eine Klasse angibt, erhält exitClass in der Response zurück; ein Request ohne dieses Feld erhält dies nicht.

Aufbrauchen des Kontingents ist kein Fehler. Ein Request, der premium angibt, nachdem das Kontingent verbraucht ist, funktioniert weiterhin: Der Standard-Pool verarbeitet ihn und die Response liefert standard. Die einzige Ausnahme ist ein Request, der eine Exit-Location angibt: Der Standard-Pool kann diese nicht berücksichtigen, daher wird er abgewiesen.

exitClass: premium erfordert einen Tarif, der Premium-Exits enthält. In einem Tarif ohne Premium-Exits verbraucht der Request niemals einen Premium-Exit: Er wird noch vor Beginn der Ausführung mit einem 403-Status und X-FourA-Limit: plan_limit_premium abgewiesen (siehe Rate Limits).

Exit-Location

Ein Premium-Exit kann von einem Standort innerhalb eines Landes ausgehen und seine Adresse so lange beibehalten, wie du sie benötigst:

{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}

Die Response nennt den Exit und das Land, aus dem er stammt:

{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}

Diese proxy ID behält alles davon. Übergib sie an Single oder Browser und der Request geht vom selben Ort aus, ohne ein anderes Feld daneben. Siehe Pinning an Exit.

Regeln:

  • Jeder Wert aus exitState, exitCity, exitAsn, exitOs und exitLifetimeMin sendet den Request ausschließlich über Premium-Exits. Der Standard-Pool erhält keinen Versuch, da er diese nicht bedienen kann.
  • Sie benötigen exitClass: premium. Ohne diese Angabe wird der Request mit einem 400-Fehler abgelehnt, der das Feld nennt.
  • exitState, exitCity und exitAsn existieren innerhalb eines Landes, daher erfordern sie genau ein Land in exitCountries. exitOs und exitLifetimeMin funktionieren mit mehreren: Der Exit wählt eines davon aus, und exitCountry in der Response gibt an, welches.
  • exitState, exitCity, exitAsn und exitOs erfordern einen Plan mit Geo-Targeting sowie Premium-Exits.
  • Wenn kein Premium-Traffic mehr übrig ist, wird der Request mit einem 403-Fehler abgelehnt, der X-FourA-Limit: plan_limit_premium enthält, da der Standard-Pool ihn nicht bedienen kann.
  • Wenn kein Premium-Exit für diesen Ort antwortet, ist die Response ein Error-Envelope wie unter exitCountries scoping beschrieben, mit dem Fehler No premium exit answered for this request und code: no_eligible_proxy. details.exitCountries ist vorhanden, wenn du eine Länderliste übergeben hast.

Die Bezeichnungen entsprechen denen, die der Proxy-Port für state, city, asn und os akzeptiert.

Browser-Profil-Rotation

Proxy rotiert Exits. Wenn eine Website den von FourA bereitgestellten Browser ablehnt statt des Exits, von dem er stammt, wechselt Proxy außerdem zu einer anderen Browser-Familie aus dem Katalog. Dadurch entsteht kein zusätzlicher Versuch: Die Rotation ändert, was ein Retry sendet, niemals, ob einer stattfindet.

Proxy merkt sich zudem für eine gewisse Zeit die Familie, die eine Website zuletzt akzeptiert hat, sodass ein späterer Aufruf derselben Website direkt mit dieser Familie statt mit dem Standard starten kann. Die Response nennt sie in profile, genau wie bei jeder durch die Rotation gewählten Familie.

Ein explizites profile, browser, os oder version auf deinem inneren request wird niemals überschrieben. Dasselbe gilt für Requests mit eigenem User-Agent- oder Cookie-Header, da eine Freigabe an die Signatur gebunden ist, mit der sie erlangt wurde.


Browser Request

POST /api/browser/

Öffnet deine URL in einer Chrome-Browser-Instanz. Die Seite lädt, JavaScript wird ausgeführt und du erhältst das vollständig gerenderte HTML samt Cookie-Jar.

Request Body

Parameter Typ Erforderlich Standard Beschreibung
url string Ja - Ziel-URL
headers object Nein - Benutzerdefinierte Header als Key-Value-Paare
cookies array Nein - Zu setzende Cookies: [{name, value, domain?}]
userAgent string Nein - Benutzerdefinierter User-Agent-String
unblocker boolean Nein true Schließt die Prüfung ab, die eine Seite vor dem Laden anfordert (eine Challenge-Seite oder ein ähnliches Gate). Standardmäßig aktiviert. Setze false, um die Antwort der Seite unverändert zu rendern, einschließlich einer Challenge-Seite.
proxy string Nein - Proxy-ID aus einer früheren Response, um denselben Exit zu pinnen. Übergib den opaken String unverändert zurück. Eine rohe Proxy-Adresse wird mit 400 Invalid proxy format abgelehnt.
timeout_ms number Nein 30000 Seitenlade-Timeout in ms (max: 120000)
checkStatus number Nein - Erwarteter HTTP-Status (Request schlägt bei Abweichung fehl)
checkText string Nein - Text, der auf der gerenderten Seite vorkommen muss
lean boolean Nein false Schließt Bilder, Schriftarten, Medien sowie Requests an bekannte Werbe-, Analyse-, Consent- und Social-Dienste aus. Die Seite selbst, ihre eigenen Skripte und Styles sowie alles, was ein Verifizierungsschritt benötigt, werden weiterhin geladen. Nutze dies, um den Traffic einer Seite zu reduzieren, zum Beispiel über einen gepinnten Premium-Exit.

Browser-Uhr an den Exit anpassen

Eine Seite kann die Zeitzone des Browsers auslesen und mit dem Land der erkannten IP abgleichen. Eine Diskrepanz ist eines der einfachsten Signale für Bot-Detektoren und lässt sich ohne Aufwand vermeiden.

Du musst nichts weiter tun. FourA liest das Land aus der proxy-ID und der Browser meldet die passende Zeitzone.

  • Es ist das Exit-Land, also das Land, das das Ziel sieht, nicht der Host-Standort des Proxys. Beide weichen oft genug voneinander ab.
  • Wenn FourA das Land des Exits nicht kennt, belässt es die Browser-Uhr unverändert, anstatt zu raten. Ein Premium-Exit hat ein bekanntes Land, wenn du eines mit exitCountries bei Proxy Request angefordert hast.
  • Nur die Uhr folgt dem Land. Accept-Language und der ausgelieferte Inhalt der Seite bleiben unberührt, sodass die Seite nicht unerwartet die Sprache wechselt.

Der Parameter userAgent

Sende userAgent und genau dieser String wird der Seite, ihren Workern und dem Ziel bereitgestellt. FourA leitet daraus auch die passenden Client Hints ab (sec-ch-ua, sec-ch-ua-platform, navigator.platform und die High-Entropy-Werte, die ein Detektor gezielt anfragt). So gibt der Request nicht einen Browser im Header und einen anderen in JavaScript an.

Der userAgent in der Response ist derjenige, der übermittelt wurde. Das ist relevant, wenn du eine Clearance erneut verwendest: Ein cf_clearance-Cookie ist an den Exit und den User-Agent gebunden, der ihn erhalten hat. Sende daher den String zurück, den die Response gemeldet hat, nicht den, von dem du annimmst, dass er verwendet wurde. Siehe Site checks.

Sendest du einen Nicht-Chromium-String (etwa einen Firefox-User-Agent), wird er unverändert übergeben, ohne angehängte Chromium-Brand-Liste.

Beispiel

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

Response:

{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
Feld Typ Beschreibung
status number HTTP-Statuscode des Ziels
headers object Response-Header
body string or object Vollständig gerenderter Seiteninhalt. HTML-String, wenn der content-type HTML ist; object, wenn die Seite JSON zurückgegeben hat und dieses automatisch geparst wurde.
cookies array Vollständige Cookie-Objekte der Seite. Jedes Cookie enthält name, value, domain, path, expires, httpOnly, secure, sameSite und weitere Cookie-Eigenschaften.
userAgent string Verwendeter Browser-User-Agent
defenseSolved boolean true, wenn bei diesem Aufruf ein Bot-Schutz erkannt und erfolgreich umgangen wurde, andernfalls false. Bestimmt, ob der Aufruf 5 oder 10 Credits kostet.
defenses object present listet jeden während des Seitenaufrufs erkannten Anbieter auf, cleared listet diejenigen auf, deren Freigabe auf der finalen Seite besteht. Ein Anbieter kann in present und nie in cleared erscheinen. Siehe Site checks.
proxy string Encodierte ID des Proxys, über den der Request lief (nur wenn beim Request ein proxy übergeben wurde). Verwende sie bei Folgeaufrufen wieder, um denselben Exit beizubehalten.
error string Fehlermeldung, falls der Request fehlgeschlagen ist

Einen Exit anheften

Ein proxy-Wert bei einem Single- oder Browser-Request heftet den Exit an, den ein vorheriger Aufruf verwendet hat. Übergib die opaque ID exakt so, wie du sie erhalten hast, niemals eine Proxy-Adresse. Eine ID aus einem Proxy-Request, die ein Land, einen Ort oder eine Lebensdauer festgelegt hat, behält diese bei, sodass der angeheftete Request kein weiteres Feld benötigt.

Drei Werte werden abgelehnt, alle mit dem Code 400:

Fehler Bedeutung
Invalid proxy format Der Wert ist keine von FourA ausgestellte ID. Eine reine Proxy-Adresse führt hierzu.
Proxy not found Die ID wurde decodiert, verweist aber nicht mehr auf einen aktiven Exit. Hole dir über einen neuen Aufruf eine frische ID.
Managed exit: this proxy id cannot be pinned to a request Der Exit existiert, wird von FourA jedoch nicht für einen spezifischen Request offengehalten. Die ID eines Premium-Exits führt hierzu, wenn dein Tarif kein Premium-Datenvolumen mehr übrig hat. Verwende die Session wieder, mit der sie zurückgegeben wurde, oder führe den Aufruf über POST /api/proxy/ aus und nutze den Exit, den dieser auswählt.

Ein angehefteter Premium-Exit wird als Premium-Traffic abgerechnet. Die Response enthält X-FourA-Exit-Class: premium, damit du dies pro Request nachvollziehen kannst. Der über den Exit geführte Traffic wird sowohl auf das Premium-Datenvolumen auf deiner Seite Nutzung & Limits als auch auf deine gesamte Bandbreite angerechnet, unabhängig davon, ob die Website die gewünschte Seite zurückgegeben hat. Das Anheften erfordert Premium-Exits in deinem Tarif und verbleibendes Kontingent; andernfalls wird die ID mit dem oben genannten Managed-Exit-400-Fehler abgewiesen.

HTTP-Statuscodes

Code Bedeutung
200 Request abgeschlossen (prüfe das innere status auf die Target-Response)
400 Ungültiger Request-Body, ungültige Parameter, Target-IP in einem privaten/reservierten Bereich, ein Target auf FourAs eigenem API-Host, eine URL mit einem nicht-kodierten Leerzeichen (Single, Proxy, Auto) oder eine Proxy-ID, die nicht gepinnt werden kann. Bei Single, Proxy und Browser wird ein fehlerhaftes Feld benannt: Invalid request: <field>: <reason>, bis zu fünf Felder. Nicht abgerechnet. Auto beantwortet denselben Fehler mit HTTP 200 und status: 400 im Body.
401 Fehlender oder ungültiger API-Key
403 Der Endpoint oder ein Parameter ist nicht in deinem Plan enthalten. X-FourA-Limit benennt es: plan_limit_feature oder plan_limit_premium.
404 Not Found: Unter diesem Pfad existiert kein Endpoint.
413 Der JSON-Request-Body ist größer als 100 KB. Die Antwort ist kein JSON und enthält kein X-FourA-Request-Id.
429 Ein Plan-Limit (X-FourA-Limit gesetzt) oder das geteilte Minutenkontingent der Plattform (kein Header)
500 Interner Serverfehler
502 Upstream unavailable: FourA konnte keine Verbindung zur Engine herstellen. Malformed JSON from backend: Die Engine hat geantwortet, aber FourA konnte die Antwort nicht lesen. Erneut versuchen.
503 Service vorübergehend deaktiviert oder ausgelastet, API key check temporarily unavailable, wenn FourA deinen Key kurzzeitig nicht bestätigen konnte (erneut versuchen nach Retry-After), oder Backend service unavailable während eines Engine-Neustarts. Bei Browser wartet eine Seite bis zu 10 Sekunden auf einen freien Browser, wenn alle belegt sind, und erhält Backend service unavailable, falls in dieser Zeit keiner frei wird.
504 Upstream timeout. Die Engine wurde nicht innerhalb des Zeitlimits für diesen Request fertig. Erhöhe timeout_ms oder versuche es erneut.

Nächste Schritte

Aktualisiert: 13. November 2026