Docs › API-Referenz › API Endpoints Referenz

API Endpoints Referenz

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

Basis-URL

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

Authentifizierung

Jeder request erfordert deinen API-Key im X-API-Key header:

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

Jede Response von /api/* enthält zwei Korrelations-Header:

Header Wert Beschreibung
X-FourA-Request-Id UUID Eindeutige ID für den Request. Wird bei jeder Response zurückgegeben, inklusive 4xx und 5xx. Protokolliere sie auf deiner Seite.
X-FourA-Credits integer Verbrauchte Credits für diesen Request. Wird bei Erfolg und Fehler zurückgegeben (die Arbeit wurde in beiden Fällen ausgeführt). Siehe Request-Ergebnisse für abrechenbare Ergebnisse.

Dieselbe Request-ID verknüpft die Vorschau von Request- und Response-Payload im Activity Log des Dashboards (wird 24 Stunden gespeichert, die letzten 200 pro Key). So kannst du den genauen Request später nachschlagen und ihn direkt aus den Aktivitäten im Playground abspielen. Gib sie an, wenn du den Support kontaktierst, um den Request in Sekunden zu finden.

$ 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 Nutzungshinweise.

Endpoints

Verwendest du diese Endpoints über MCP? Der @fouradata/mcp server stellt alle vier Endpoints als native MCP-Tools (foura_auto, foura_single, foura_proxy, foura_browser) mit den gleichen Eingabeformaten bereit, plus einem offload_large Opt-in für die token-freundliche Verarbeitung großer Responses.

FourA bietet vier Request-Endpoints, jeder optimiert für ein anderes Szenario:

Endpoint Am besten für
POST /auto/ Smart fetch. Du übergibst eine URL, FourA wählt den günstigsten funktionierenden Weg (direkt, rotierter Proxy oder Browser) und merkt sich, was pro Host funktioniert.
POST /single/ Schnelle HTTP-Requests, statische Seiten, APIs
POST /proxy/ Geschützte Seiten mit automatischer Proxy-Rotation, optionales für das Ziel sichtbares Country-Scoping
POST /browser/ JavaScript-gerenderte Seiten, SPAs
GET /profiles Der Browser-Profil-Katalog für single und proxy. Öffentlich, kein API-Key.

Für eine detaillierte Anleitung, wann du welchen wählst, siehe Den richtigen Endpoint wählen und den Smart Fetch Guide.

Einschränkungen der Ziel-URL

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

{ "error": "Target <ip> resolves to a private/reserved IP" }

Smart Fetch (Auto)

POST /api/auto/

Du übergibst eine URL und optionale validate Regeln. FourA geht eine kostenoptimierte Leiter durch (günstiger direkter Test, rotierender Proxy, vollständiger Browser) und stoppt auf der ersten Stufe, die eine Response zurückgibt, die deine Regeln akzeptieren. Bei wiederholten Aufrufen desselben Hosts wird stattdessen eine warme Session wiederholt, sodass der zweite Treffer günstig ist.

Du stellst keine Retries, Poolgrößen oder Proxy-Anzahlen ein. FourA lernt diese pro Host.

Request Body

Parameter Typ Erforderlich Standard Beschreibung
url string Ja - Ziel-URL
method string Nein "GET" HTTP-Methode
headers [string, string][] Nein - Benutzerdefinierte Header als [Name, Wert]-Paare
data any Nein - Request Body für Non-GET Requests
validate object Nein - Erfolgskriterien, gleiche Struktur wie validate eines Single Requests (siehe unten). Teile Auto mit, wie eine echte Seite aussieht, damit es Inhalt von einer Challenge-Seite unterscheiden kann.
returnSession boolean Nein true Schließt die gewinnende Session (proxy, cookies, userAgent) in die Response ein, damit du sie über /api/single/ oder /api/browser/ wiederholen kannst.
forceProxy boolean Nein true Leitet immer über einen rotierenden Proxy. Setze false, um den günstigeren direkten Weg zu erlauben, wenn das Ziel dies zulässt (einige Abwehrmechanismen sind bei Proxy-Traffic strenger).
timeout_ms integer Nein 120000 Gesamtzeitbudget für den gesamten Call, in Millisekunden. Alle Unterversuche laufen innerhalb dieses Budgets. Min 5000, Max 180000.
ignoreProxies string[] Nein - Proxy-IDs, die bei jedem Unterversuch vermieden werden sollen. Nutze IDs, die von vorherigen /api/auto/ oder /api/proxy/ Responses zurückgegeben wurden.
followRedirects integer Nein 5 Maximale Redirects, die auf den günstigen Leiterstufen verfolgt werden sollen. 0 zum Deaktivieren. Max 20.

Response

{
  "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..."
  }
}
Feld Typ Beschreibung
status number HTTP-Status vom Ziel.
data string oder object Response Body.
headers array oder object Response Headers des Ziels. Single- und Proxy-Stufen geben ein Array von Per-Hop Header-Objekten zurück; Browser-Stufen geben ein flaches Objekt zurück.
meta.rung string Welche Ladder-Stufe die Response geliefert hat. Eins von: probe (günstiger direkter Request), proxy (rotierender Proxy), browser (vollständiges Browser-Rendering), cache (warme Session wiederholt) oder fail (keine Stufe lieferte eine akzeptierte Response).
meta.solved boolean Ob während dieses Calls eine Bot-Herausforderung (Challenge) gelöst wurde.
meta.attempts number Teilversuche vor dem Erfolg.
meta.credits number Für diesen Call verbrauchte Credits. Entspricht X-FourA-Credits.
session.proxy string Kodierte ID des Proxys, der die Response geliefert hat. Verwende sie bei einem Single- oder Browser-Request wieder. Vorhanden, wenn returnSession gleich true ist.
session.cookies array Cookies vom erfolgreichen Versuch. Vorhanden, wenn returnSession gleich true ist.
session.userAgent string User-Agent, der beim erfolgreichen Versuch verwendet wurde. Vorhanden, wenn returnSession gleich true ist.
error string Fehlermeldung, falls der Call fehlschlug.

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 ist ein Koordinator. Er ruft intern Single, Proxy oder Browser auf und leitet deinen API-Key an jeden Sub-Call weiter. Jeder Sub-Call erscheint in deinem Aktivitätsprotokoll; der äußere /api/auto/ Call fügt keine separate abrechenbare Zeile hinzu.
  • Übergib validate.data.accept mit einem Substring, den nur die echte Seite enthält. Ohne diesen Wert kann Auto eine echte 200 nicht von einem Challenge Interstitial mit Status 200 unterscheiden.
  • timeout_ms begrenzt den gesamten Call. Ein kalter erster Zugriff auf eine geschützte Seite kann mehrere Dutzend Sekunden dauern; wiederverwendete warme Sessions enden normalerweise in unter einer Sekunde.

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 method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Ja - Ziel-URL. Verwende {ts} überall 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 Sende realistische Browser-Header (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Standardmäßig aktiviert. Setze false, um eine einfache Client-Signatur zu senden.
timeout_ms number Nein 15000 Gesamt-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-Response-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 deaktiviert Maximale Anzahl zu verfolgender Redirects (0-20). Weglassen zur Deaktivierung.
tryJsonData boolean Nein false Parse Response Body als JSON, falls möglich
returnBuffer boolean Nein false Gib den rohen Buffer anstelle des dekodierten Strings zurück
data any Nein - Request Body (String oder Objekt, wird automatisch nach JSON serialisiert)
proxy string Nein - Proxy-ID aus einer früheren Response, um denselben Exit beizubehalten. Übergib den opaken String unverändert zurück. Eine rohe Proxy-Adresse wird mit 400 Invalid proxy format abgelehnt.
browser string Nein Chrome Zu präsentierender Browser: Chrome, Edge, Safari, Firefox oder Tor. Siehe Browser profiles.
os string Nein - Zu präsentierendes Betriebssystem: Windows, macOS, Android oder iOS. Ein Familienname akzeptiert alle seine Versionen.
version string Nein neueste Zu präsentierende Browser-Version, wie im Katalog aufgeführt. Die neueste Übereinstimmung gewinnt, wenn mehrere zutreffen.
profile string Nein - Exakte Profil-ID von GET /api/profiles, anstelle der drei obigen Felder.
validate object Nein - Regeln zur Validierung der Response (siehe unten)

Browser profiles

Standardmäßig präsentiert ein Request den neuesten Google Chrome. Einige Ziele akzeptieren einen Browser und lehnen einen anderen ab, daher engen browser, os und version einen Katalog gemessener Profile ein, und profile wählt eines nach ID aus.

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

Regeln:

  • Die Auswahl erfordert unblocker (standardmäßig aktiviert). Wenn der Unblocker deaktiviert ist, werden keine Browser-Header gesendet. Die Request wird daher abgelehnt, anstatt unvollständig angewendet zu werden.
  • Wenn mehrere Profile zutreffen, gewinnt die neueste Version.
  • Eine Kombination, die der Katalog nicht anbietet, liefert einen Fehler mit den verfügbaren Optionen. Die 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 erfordert keinen API-Key:

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

osFamily ist der Wert zum Filtern beim Erstellen eines Pickers; os behält den Release-Namen zur Anzeige.

Validierungsregeln

Das Objekt validate lässt dich Bedingungen für Erfolg und Misserfolg definieren. Trifft eine Bedingung in fail zu, gilt der Request als fehlgeschlagen. Sind accept-Bedingungen gesetzt, gelten nur übereinstimmende Responses als erfolgreich.

{
  "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 Header-Schlüssel-Wert-Paare, die vorhanden sein müssen
validate.headers.fail object Header-Schlüssel-Wert-Paare, die einen Fehler auslösen
validate.data.accept string[] Strings, die im Response Body vorhanden sein müssen
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": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342,
  "proxy": "A1B2C3"
}

Wenn das Ziel beim Abruf des Bodys eine Bot-Prüfung durchführt, enthält die Response auch ein defense Objekt, das den Anbieter benennt und angibt, ob die Prüfung 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 vom Ziel
headers array Ein Objekt pro Redirect-Hop. Jedes hat ein result-Feld mit der Statuszeile sowie jedem Response-Header. Multi-Value-Header (Set-Cookie, Link, WWW-Authenticate) werden als Arrays von Strings zurückgegeben.
data string/object Response-Body (JSON, wenn tryJsonData true ist)
total_time number Gesamte Request-Zeit in Sekunden
proxy string Codierte ID des Proxys, über den der Request lief (nur, wenn proxy im Request übergeben wurde). Verwende sie für Folgeaufrufe wieder, um denselben Exit festzulegen.
defense object Nur vorhanden, wenn das Ziel bei diesem Request eine Bot-Prüfung durchgeführt hat. defense.solved gibt an, ob die Prüfung bestanden wurde. Siehe Anti-Bot-Abwehrmaßnahmen für alle Felder und die vollständige Anbieterliste.
error string Fehlermeldung, falls der Request fehlschlug

Proxy-Request

POST /api/proxy/

Leitet deinen Request durch rotierende Proxys mit automatischem Retry bei Fehlern. Optional kann die Auswahl auf eine bestimmte Gruppe von zielseitig sichtbaren Exit-Ländern eingegrenzt werden.

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 Gesamt-Timeout für alle Versuche in ms (max. 120000)
maxTries number Nein 5 Maximale Proxy-Rotationsversuche (max. 90)
ignoreProxies string[] Nein - Proxy-IDs, die von der Rotation ausgeschlossen werden sollen (verwende IDs aus vorherigen Responses)
exitCountries string[] Nein - Strikte Allowlist für zweistellige, zielseitig sichtbare Ländercodes (z. B. ["CZ", "GB"]). Werte werden getrimmt, in Großbuchstaben umgewandelt und dedupliziert. Proxys mit unbekannten Exits werden ausgeschlossen, und der Request fällt nie auf ein nicht angefordertes Land zurück.

Scoping für exitCountries

Die Auswahl nutzt die neuesten verfügbaren, zielseitig sichtbaren Länder-Metadaten, die normalerweise etwa alle zehn Minuten aktualisiert werden. Es findet kein Live-Geolocation-Lookup während des Requests statt. Leite das bereitstellende Land nicht aus der Proxy-Host-Adresse ab.

Falls der aktuelle Pool keine Treffer für die angeforderten Länder aufweist, liefert die Response einen HTTP 200 mit einem Fehler-Envelope:

{
  "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 ausdrücklich ä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 Identifier 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 Zweistelliger, vom Ziel sichtbarer Ländercode des Proxys, der den Request bedient hat. Nur vorhanden, wenn der Request exitCountries gesetzt hat. Prüfe immer, ob es einer der angeforderten Codes ist, bevor du der Response vertraust.
total number Äußere Wall-Clock-Dauer in Sekunden (float). Beinhaltet Proxy-Auswahl, Retries und den erfolgreichen Versuch. total_time ist nur der innere Request; total ist immer >= total_time.
error string Fehlermeldung, falls der Request fehlgeschlagen ist. Bei einem Scope-Miss ist code gleich no_eligible_proxy und details.exitCountries gibt den normalisierten Scope zurück.

Alle Response-Felder des Single Requests sind ebenfalls enthalten, darunter defense: Ein Proxy-Versuch, der auf einen Bot-Check trifft, meldet dies auf die gleiche Weise wie Single.

Browser Request

POST /api/browser/

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

Request Body

Parameter Typ Erforderlich Standard Beschreibung
url string Ja - Ziel-URL
headers object Nein - Benutzerdefinierte Header als Schlüssel-Wert-Paare
cookies array Nein - Zu setzende Cookies: [{name, value, domain?}]
userAgent string Nein - Benutzerdefinierter User-Agent-String
unblocker boolean Nein true Automatisches Lösen gängiger Bot-Challenges (Cloudflare Clearance, ähnliche Gates) während des Seitenladens. Standardmäßig aktiviert. Setze false, um das zu rendern, was die Seite zurückgibt, einschließlich einer Challenge-Seite, ohne sie zu lösen.
proxy string Nein - Proxy ID aus einer früheren Response, um denselben Ausgang festzupinnen. Übergib den undurchsichtigen String unverändert zurück. Eine rohe Proxy-Adresse wird mit 400 Invalid proxy format abgelehnt.
timeout_ms number Nein 30000 Timeout für das Laden der Seite in ms (max: 120000)
checkStatus number Nein - Erwarteter HTTP-Status (Request schlägt fehl, wenn abweichend)
checkText string Nein - Text, der in der gerenderten Seite erscheinen muss

Example

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"]},
  "proxy": "A1B2C3"
}
Feld Typ Beschreibung
status number HTTP-Statuscode vom Ziel
headers object Response Header
body string oder object Vollständig gerenderter Seiteninhalt. String-HTML, wenn Content-Type HTML ist; Object, wenn die Seite JSON zurückgegeben hat und 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 eine Bot-Abwehr erkannt und bei diesem Aufruf erfolgreich umgangen wurde. Andernfalls nicht vorhanden. Bestimmt die Kosten von 15 oder 30 Credits.
defenses object present listet jeden Anbieter auf, der beim Laden der Seite erkannt wurde, cleared listet diejenigen auf, deren Freigabe die finale Seite besitzt. Ein Anbieter kann in present auftauchen und nie in cleared. Siehe Anti-Bot Defenses.
proxy string Kodierte ID des Proxys, über den der Request gesendet wurde (nur wenn ein proxy im Request übergeben wurde). Verwende sie bei Folgeaufrufen wieder, um denselben Ausgang zu behalten.
error string Fehlermeldung, wenn der Request fehlgeschlagen ist

HTTP-Statuscodes

Code Bedeutung
200 Request abgeschlossen (prüfe inneres status für die Zielantwort)
400 Ungültiger Request-Body, Parameter oder Ziel-IP in einem privaten/reservierten Bereich
401 Fehlender oder ungültiger API-Key
429 Rate Limit überschritten
500 Interner Serverfehler
502 Upstream unavailable. FourA hat seine Engine erreicht, aber die Antwort war unbrauchbar. Wiederhole den Vorgang.
503 Dienst vorübergehend deaktiviert oder ausgelastet, oder Backend service unavailable während eine Engine neu startet
504 Upstream timeout. Die Engine wurde innerhalb des Zeitbudgets für diesen Request nicht fertig. Erhöhe timeout_ms oder wiederhole den Vorgang.

Nächste Schritte

Aktualisiert: 12. August 2026
API-Fehler →