# Site-Checks

> URL: https://foura.ai/de/docs/api/site-checks
> Updated: 2026-11-11
> Index: https://foura.ai/llms.txt

Wenn ein Ziel auf dem Weg zu der von dir angeforderten Seite einen Bot-Check durchführt, teilt FourA dir das mit. Jeder Request, der auf einen solchen Check trifft, enthält ein Feld mit dem Namen des Systems, der Angabe, ob die Überprüfung bestanden wurde, und (bei Erfolg) dem Clearance-Token, das du wiederverwenden kannst, damit der nächste Aufruf ihn überspringt.

Diese Seite ist die Referenz für diese Felder. Strategien dazu findest du unter [Geschützte Websites](https://foura.ai/docs/guides/protected-sites).

## Wo sich das Feld befindet

| Endpoint | Feld | Vorhanden wenn |
|----------|-------|----------------|
| `POST /api/single/` | `defense` (Objekt) | In der Response wurde ein Bot-Check erkannt |
| `POST /api/proxy/` | `defense` (Objekt) | Ebenso, gemeldet vom antwortenden Versuch |
| `POST /api/browser/` | `defenseSolved` (Boolean) und `defenses` (Objekt) | Immer, bei einer geladenen Seite. `defenseSolved` ist `false` und `defenses` ist leer, wenn nichts erkannt wurde. |
| `POST /api/auto/` | `meta.solved` (Boolean) | Bei jeder Antwort, sobald die Ladder gestartet wurde. `true`, wenn irgendwo in der Ladder ein Check bestanden wurde. Ein Body, der die Validierung nicht besteht, oder ein Host, der nicht aufgelöst werden kann, wird vor der Ladder beantwortet, ohne `meta`. |

Fehlen bedeutet, dass nichts erkannt wurde. Interpretiere ein fehlendes `defense` nicht als Fehler.

Bei Single und Proxy erfordert das Reporting `unblocker`, was standardmäßig aktiviert ist. Mit `unblocker: false` forderst du die Seite exakt so an, wie sie ankam; Single gibt die Challenge daher unverändert zurück und Browser rendert sie, ohne sie zu lösen.

## `defense` bei Single und Proxy

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "hashes": 1048576,
    "complexity": 20,
    "cookie": "_I_=<clearance>"
  }
}
```

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `vendor` | string | Das System, auf das sich dieser Datensatz bezieht: dasjenige, das gelöst wurde, oder das wichtigste erkannte System. Siehe die Anbieterliste unten. |
| `solved` | boolean | `true` bedeutet, dass die Prüfung bestanden wurde und `data` die eigentliche Seite ist. `false` bedeutet, dass `data` die Challenge-Seite sein kann. |
| `present` | string[] | Jedes in dieser Response erkannte System. Kann mehr Namen enthalten als `vendor`, auch Namen, die bisher niemand auflöst. |
| `ms` | number | Für das Bestehen der Prüfung aufgewendete Millisekunden. Nur bei erfolgreichem Clear. |
| `hashes` | number | Wie viel Rechenaufwand die Challenge verlangt hat. Nur bei erfolgreichem Clear. |
| `complexity` | number | Der von der Challenge gemeldete Schwierigkeitsgrad. Nur bei erfolgreichem Clear und nur, wenn die Challenge einen angibt. |
| `answers` | number | Wie viele akzeptierte Antworten geliefert wurden, falls die Challenge mehrere statt nur einer verlangt. Nur bei erfolgreichem Clear. |
| `retry` | string | Vorhanden, wenn der Body aus einem Retry statt aus einem Clear stammt: `refusal-cookies`, `amazon-continue`, `reddit-js-check` oder `verify-challenge`. Siehe unten. |
| `cookie` | string | Das Jar zum erneuten Senden: die durch das Lösen erhaltene Freigabe oder die bei einer Ablehnung vergebene Session. |

`solved: false` ist der Fall, nach dem du verzweigen solltest. FourA liefert eine Challenge-Seite niemals als Inhalt aus, daher signalisiert dir das Flag, dass der Body eskaliert und nicht geparst werden muss.

### `retry: "refusal-cookies"`

Manche Websites verwenden kein Puzzle. Sie lehnen den ersten Request ab, setzen Cookies bei der Ablehnung und liefern die eigentliche Seite an jeden aus, der diese Cookies zurücksendet. Die Artikelseiten von eBay sind der Referenzfall.

In diesem Fall sendet FourA sie für dich zurück und übergibt dir die Seite. Die Response enthält dann `retry: "refusal-cookies"`:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai"],
    "retry": "refusal-cookies",
    "cookie": "bm_sv=...; dp1=..."
  }
}
```

Lies es so:

- **`solved` bleibt `false`.** Das Beantworten eines Handshakes ist kein Lösen einer Challenge und ändert nie die Kosten des Calls. Dir wird der Request berechnet, den du gestellt hast.
- **`data` ist echter Inhalt**, keine Challenge-Seite. Dies ist der einzige Fall, in dem `solved: false` nicht bedeutet, dass der Body eine Eskalation benötigt. Genau deshalb existiert dieses Feld.
- **`cookie` ist die Session, die die Seite ausgegeben hat.** Spiele sie genauso wieder ab, wie du ein Clearance wiederholen würdest, und nachfolgende Seiten überspringen die Ablehnung.
- Ein Retry und ein Clear können beide bei einem einzigen Request auftreten. Wenn die Antwort des Retrys eine Challenge war, die FourA lösen kann, erhältst du `solved: true` mit den Feldern des Anbieters **und** `retry: "refusal-cookies"` daneben.

`vendor` liefert `unknown`, wenn ein Retry den Inhalt geliefert hat und unterwegs kein System erkannt wurde. `present` ist dann ein leeres Array.

### `retry: "amazon-continue"`

Amazon antwortet manchmal mit einem Ein-Klick-Robot-Check: eine kleine Seite, die dich auffordert zu klicken, um weiter einzukaufen, wobei die Antwort bereits ausgefüllt ist. Wenn `unblocker` aktiv ist (Standard), klicken Single und Proxy auf diesen Button über denselben Exit innerhalb deines `timeout_ms` und fordern deine Seite mit den gesetzten Cookies erneut an. Wenn das die Seite öffnet, enthält die Response `retry: "amazon-continue"`:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai", "amazon"],
    "retry": "amazon-continue",
    "cookie": "ak_bmsc=...; ..."
  }
}
```

Lies es wie einen Retry bei abgelehnten Cookies. `solved` bleibt `false`, `data` ist die eigentliche Seite, dir wird der von dir gesendete Request berechnet und `cookie` ist das Jar, das du bei Folgeaufrufen wiederverwenden kannst. Suche nach `amazon` in `present` statt in `vendor`: Die Prüfseite setzt oft ein Cookie, das FourA ebenfalls erkennt, und `vendor` nennt das erste System in der Liste.

Die Bildvariante derselben Prüfung, bei der ein Mensch die Antwort ablesen muss, wird gemeldet und unverändert weitergegeben. Ebenso ein Klick, der nur die Prüfung erneut lädt. In beiden Fällen wird diese Seite nicht berechnet (siehe [Was es kostet](#what-it-costs)).

### `retry: "reddit-js-check"`

Reddit antwortet manchmal mit einem einfachen Seitencheck: eine kleine Seite mit einem versteckten Formular und einem Skript, das dieses Formular ausfüllt. Wenn `unblocker` aktiviert ist (Standardeinstellung), übermitteln Single und Proxy dieses Formular über denselben Exit innerhalb deines `timeout_ms` und rufen deine Seite mit den gesetzten Cookies erneut ab. Wenn sich die Seite dadurch öffnet, enthält die Response `retry: "reddit-js-check"`:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "reddit",
    "solved": false,
    "present": ["reddit"],
    "retry": "reddit-js-check",
    "cookie": "edgebucket=...; ..."
  }
}
```

Lies es wie einen `amazon-continue` Retry. `solved` bleibt `false`, `data` ist die echte Seite, dir wird der ausgeführte Request berechnet und `cookie` ist das Jar für Folgeseiten. Wenn der Check wiederholt erscheint, belässt FourA die Seite im Originalzustand und diese Seite wird nicht berechnet.

### `retry: "verify-challenge"`

Manche Websites öffnen zunächst eine kurze eigene Prüfseite: ein Spinner und ein Skript, das dich nach Abschluss des Checks zur Seite weiterleitet. Wenn `unblocker` aktiviert ist (Standard), schließen Single und Proxy diesen Check auf demselben Exit innerhalb deines `timeout_ms` ab und fordern deine Seite mit dem gesetzten Cookie erneut an. Wenn dies die Seite öffnet, enthält die Response `retry: "verify-challenge"`:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "verify-challenge",
    "solved": false,
    "present": ["verify-challenge"],
    "retry": "verify-challenge",
    "cookie": "token=..."
  }
}
```

Lies es wie einen `reddit-js-check` Retry. `solved` bleibt `false`, `data` ist die eigentliche Seite, dir wird der gesendete Request berechnet und `cookie` ist das Jar zum Wiederholen auf Folgeseiten. Wenn die Prüfseite unbeantwortet bleibt, wird sie nicht berechnet.

## `defenses` im Browser

```json
{
  "status": 200,
  "body": "<!doctype html>...",
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {
    "present": ["cloudflare"],
    "cleared": ["cloudflare"]
  }
}
```

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `defenseSolved` | boolean | `true`, wenn während des Ladens ein System erkannt wurde und dessen Clearance auf der finalen Seite vorliegt. Dieses Flag entscheidet, ob der Aufruf 5 oder 10 Credits kostet. |
| `defenses.present` | string[] | Jedes System, das zu irgendeinem Zeitpunkt während des Seitenladens erkannt wurde, nicht nur in der finalen Response. Eine Überprüfung ist ein reales Ereignis, und bis die eigentliche Seite eintrifft, ist die Challenge-Response längst vergangen. |
| `defenses.cleared` | string[] | Die Systeme, deren Clearance die finale Seite besitzt. |

Ein Name in `present`, der `cleared` nie erreicht, ist ein System, das FourA erkannt hat, ohne dafür eine Clearance zu erhalten: eines, das es noch nicht abschließen kann, oder eines der wenigen, die Browser anders verarbeitet (siehe [Was heute gecleart wird](#what-gets-cleared-today)). Diese erhöhen den Preis eines Aufrufs nie.

## Anbieter

| `vendor`-Wert | Das System |
|----------------|-----------|
| `cloudflare` | Cloudflare-Challenges und Bot-Management |
| `sgcaptcha` | SiteGround-Website-Prüfung |
| `datadome` | DataDome |
| `perimeterx` | PerimeterX |
| `akamai` | Akamai Bot Manager |
| `incapsula` | Imperva Incapsula |
| `awswaf` | AWS WAF-Challenge |
| `ebay-splashui` | eBays eigene Challenge |
| `reddit` | Reddits eigene Prüf- und Ablehnungsseiten |
| `verify-challenge` | Eine seigene Prüfseite, die dich weiterleitet, sobald ihre Prüfung abgeschlossen ist |
| `amazon` | Amazons Robot-Prüfung |
| `hcaptcha` | hCaptcha |
| `recaptcha` | reCAPTCHA |
| `unknown` | Es wurde kein System erkannt. Erscheint nur zusammen mit `retry`, wo der Eintrag existiert, um den Retry statt eines Anbieters zu melden. |

### Was heute gecleart wird

| Endpoint | Cleart |
|----------|--------|
| Single, Proxy | `sgcaptcha`, `ebay-splashui`. Beide sind rechnerisch statt visuell, daher wird kein Browser benötigt. |
| Browser | `cloudflare`, `sgcaptcha` |

Einige weitere werden ohne Clear verarbeitet. Single und Proxy betätigen Amazons Ein-Klick-Robot-Prüfung und melden sie als `retry: "amazon-continue"`, übermitteln Reddits schlanke Seitenprüfung und melden sie als `retry: "reddit-js-check"` und schließen die seigene Prüfseite einer Website ab und melden sie als `retry: "verify-challenge"`. Browser wartet bis zu 10 Sekunden darauf, dass dieselbe Prüfseite ihn weiterleitet. Browser klickt auf Amazons Button und wartet, während Akamais Sensorseite, AWS WAFs Challenge-Seite, DataDomes Geräteprüfung oder eBays eigene Challenge-Seite die nächste Seite selbstständig lädt, und liefert diese Seite dann zurück. Falls diese Seite nie eintrifft, liefert Browser die gehaltene Seite innerhalb deines `timeout_ms` zurück. Bei Browser erscheinen diese Namen in `defenses.present`, nie in `cleared`, und der Aufruf kostet 5.

Alles andere auf der Liste wird erkannt und gemeldet, mehr nicht. Diese Aufteilung verschiebt sich, sobald FourA weitere Systeme verarbeiten lernt; lies daher `solved`, anstatt dich auf diese Tabelle zu verlassen.

Zwei Randnotizen:

- `hcaptcha` und `recaptcha` sind ebenfalls gewöhnliche Formular-Widgets. Sie werden nur gemeldet, wenn die Response dich tatsächlich blockiert hat (403, 429 oder 503). Eine Checkout-Seite mit einem Verifizierungs-Widget in einem Formular meldet also keine Defense.
- Hinter Cloudflare zu liegen, ist keine Defense. `cloudflare` erscheint, wenn eine echte Challenge oder ein Bot-Management-Artefakt in der Response vorliegt, nicht bloß weil eine Seite Cloudflare nutzt.

## Clearance erneut abspielen

`defense.cookie` ist der eigentliche Zweck des Feldes. Eine Clearance ist an den Exit-Knoten und den User-Agent gebunden, über die sie erlangt wurde. Sende sie über dasselbe Paar erneut, und die Prüfung wird nicht noch einmal ausgeführt.

```python
import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# 1) First call pays for the clear.
first = requests.post(f"{API}/api/proxy/", headers=H, json={
    "maxTries": 5,
    "request": {"method": "GET", "url": "https://example.com/catalog"},
}).json()

defense = first.get("defense", {})
if defense.get("solved"):
    clearance = defense["cookie"]
    exit_id = first["proxy"]

    # 2) Follow-up pages skip the check: same exit, same clearance.
    for page in range(2, 6):
        r = requests.post(f"{API}/api/single/", headers=H, json={
            "method": "GET",
            "url": f"https://example.com/catalog?page={page}",
            "proxy": exit_id,
            "headers": [["Cookie", clearance]],
        }).json()
        print(page, r["status"])
```

Der erste Aufruf trägt die Kosten des Clears. Jeder Replay ist ein normaler Request zum regulären Preis.

Drei Dinge bringen einen Replay zum Scheitern:

1. **Ein anderer Exit.** Pinne die Proxy-ID, die die Response des Clears zurückgegeben hat. Siehe [Reuse a Proxy Across Requests](https://foura.ai/docs/how-to/reuse-a-proxy).
2. **Ein anderer User-Agent.** Browser-Responses geben den genutzten `userAgent` zurück. Sende ihn zusammen mit dem Cookie zurück.
3. **Ablauf.** Clearances haben eigene, vom Ziel gesetzte Gültigkeitsdauern. Die von SiteGround gilt etwa 30 Tage für die gesamte Website; eine Cloudflare-Clearance ist meist deutlich kürzer. Behandle eine Clearance wie einen Cache: Wenn Replays wieder Challenges zurückgeben, führe einen neuen Aufruf aus und übernimm die neue Clearance.

## Kosten

Ein gelöster Check ändert den Preis nur bei Browser:

| Engine | Base | Cleared defense |
|--------|------|-----------------|
| Single | 1 (2 mit `unblocker`) | Keine Änderung |
| Proxy | 2 (4 mit `unblocker`) | Keine Änderung |
| Browser | 5 | 10 |

Browser berechnet 10 nur dann, wenn der Solver aktiv war und ein System tatsächlich gelöst wurde. Ein erkanntes, aber nicht gelöstes System kostet 5, genau wie eine Seite ohne jeglichen Check.

Eine von FourA erkannte Check- oder Sperrseite mit HTTP 200 (beispielsweise der Robot-Check von Amazon, die Verifizierungsseite von Reddit oder die Challenge-Seite von eBay) wird an keinem Endpoint abgerechnet. Responses von Single, Proxy und Browser benennen sie in `X-FourA-Check-Page`.

## Mit `validate` kombinieren

`defense` zeigt dir an, dass ein Check aufgetreten ist. `validate` teilt FourA mit, wie die echte Seite aussieht. Dadurch schlägt ein Request fehl, statt dir eine Zwischenseite mit zufälligem HTTP 200 zu liefern.

```json
{
  "method": "GET",
  "url": "https://example.com/product/42",
  "validate": {
    "data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
  }
}
```

Bei `POST /api/auto/` verhindert `validate`, dass die Eskalationskette eine Challenge-Seite fälschlicherweise als erfolgreich akzeptiert.

## Verwandte Themen

- [Geschützte Websites](https://foura.ai/docs/guides/protected-sites): Welche Engine für welche Schutzstufe geeignet ist
- [API-Endpunkte](https://foura.ai/docs/api/endpoints): Request- und Response-Referenz für alle vier Endpunkte
- [Proxy über Requests hinweg wiederverwenden](https://foura.ai/docs/how-to/reuse-a-proxy): Den Exit festlegen, an den eine Freigabe gebunden ist
- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): Wie sich `meta.solved` in die Kette einfügt
- [Response-Header](https://foura.ai/docs/api/response-headers): Wo die Credit-Kosten eines Aufrufs aufgeführt werden
