# Site checks

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

When a target runs a bot check on the way to the page you asked for, FourA tells you. Every request that meets one comes back with a field naming the system, whether the check was cleared, and (on a clear) the clearance you can replay so the next call skips it.

This page is the reference for those fields. For strategy, see [Protected sites](https://foura.ai/docs/guides/protected-sites).

## Where the Field Lives

| Endpoint | Field | Present when |
|----------|-------|--------------|
| `POST /api/single/` | `defense` (object) | A bot check was recognised on the response |
| `POST /api/proxy/` | `defense` (object) | Same, reported by the attempt that answered |
| `POST /api/browser/` | `defenseSolved` (boolean) and `defenses` (object) | Always, on a page that loaded. `defenseSolved` is `false` and `defenses` is empty when nothing was recognised. |
| `POST /api/auto/` | `meta.solved` (boolean) | On every answer once the ladder has started. `true` when a check was cleared somewhere on the ladder. A body that fails validation or a host that doesn't resolve is answered before the ladder, without `meta`. |

Absence means nothing was recognised. Don't read a missing `defense` as a failure.

On Single and Proxy, reporting needs `unblocker`, which is on by default. With `unblocker: false` you asked for the page exactly as it came, so Single hands back the challenge untouched and Browser renders it without solving.

## `defense` on Single and 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>"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `vendor` | string | The system this record is about: the one that was cleared, or the main one met. See the vendor list below. |
| `solved` | boolean | `true` means the check was cleared and `data` is the real page. `false` means `data` may be the challenge page. |
| `present` | string[] | Every system recognised on this response. Can hold more names than `vendor`, and can hold names nobody clears yet. |
| `ms` | number | Milliseconds spent clearing the check. Only on a clear. |
| `hashes` | number | How much computational work the challenge asked for. Only on a clear. |
| `complexity` | number | The difficulty the challenge declared. Only on a clear, and only where the challenge reports one. |
| `answers` | number | How many accepted answers were supplied, for challenges that want several rather than one. Only on a clear. |
| `retry` | string | Present when the body came back from a retry rather than from a clear: `refusal-cookies`, `amazon-continue`, `reddit-js-check` or `verify-challenge`. See below. |
| `cookie` | string | The jar to replay: the clearance a clear earned, or the session a refusal handed out. |

`solved: false` is the case worth branching on. FourA never presents a challenge page as content, so the flag is your signal that the body needs escalation rather than parsing.

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

Some sites don't run a puzzle. They refuse the first request, set cookies on the refusal, and serve the real page to anyone who sends those cookies back. eBay's item pages are the reference case.

When that happens, FourA sends them back for you and hands you the page. The response then carries `retry: "refusal-cookies"`:

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

Read it like this:

- **`solved` stays `false`.** Answering a handshake isn't clearing a challenge, and it never changes what the call costs. You're billed for the request you made.
- **`data` is real content**, not a challenge page. This is the one case where `solved: false` doesn't mean the body needs escalation, which is why the field exists.
- **`cookie` is the session the site handed out.** Replay it the same way you'd replay a clearance and the follow-up pages skip the refusal.
- A retry and a clear can both happen on one request. If the retry's answer turned out to be a challenge that FourA can clear, you get `solved: true` with the vendor's own fields **and** `retry: "refusal-cookies"` beside them.

`vendor` reads `unknown` when a retry produced the content and no system was recognised on the way. `present` is then an empty array.

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

Amazon sometimes answers with a one-button robot check: a small page that asks you to click to continue shopping, with the answer already filled in. With `unblocker` on (the default), Single and Proxy press that button on the same exit, inside your `timeout_ms`, and ask for your page again with the cookies it set. When that opens the page, the response carries `retry: "amazon-continue"`:

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

Read it like a refusal-cookies retry. `solved` stays `false`, `data` is the real page, you're billed for the request you made, and `cookie` is the jar to replay on follow-up pages. Look for `amazon` in `present` rather than in `vendor`: the check page often sets a cookie FourA also recognises, and `vendor` names the first system on the list.

The picture version of the same check, where a person has to read the answer, is reported and left as it came. So is a press that only brings the check back. Either way that page isn't billed (see [What It Costs](#what-it-costs)).

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

Reddit sometimes answers with a light page check: a small page holding a hidden form and a script that fills the form in. With `unblocker` on (the default), Single and Proxy submit that form on the same exit, inside your `timeout_ms`, and ask for your page again with the cookies it set. When that opens the page, the response carries `retry: "reddit-js-check"`:

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

Read it like an `amazon-continue` retry. `solved` stays `false`, `data` is the real page, you're billed for the request you made, and `cookie` is the jar to replay on follow-up pages. When the check keeps coming back, FourA leaves the page as it came, and that page isn't billed.

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

Some sites open with a short check page of their own: a spinner and a script that sends you on to the page once the check completes. With `unblocker` on (the default), Single and Proxy complete that check on the same exit, inside your `timeout_ms`, and ask for your page again with the cookie it set. When that opens the page, the response carries `retry: "verify-challenge"`:

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

Read it like a `reddit-js-check` retry. `solved` stays `false`, `data` is the real page, you're billed for the request you made, and `cookie` is the jar to replay on follow-up pages. When the check page comes back unanswered, it isn't billed.

## `defenses` on Browser

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

| Field | Type | Description |
|-------|------|-------------|
| `defenseSolved` | boolean | `true` when a system was met during the load and its clearance is held on the final page. This is the flag that decides whether the call costs 5 or 10 credits. |
| `defenses.present` | string[] | Every system recognised at any point during the page load, not just on the final response. A check is something that happened, and by the time the real page arrives the challenge response is long gone. |
| `defenses.cleared` | string[] | The systems whose clearance the final page holds. |

A name in `present` that never reaches `cleared` is a system FourA recognised without earning a clearance for it: one it can't complete yet, or one of the few Browser handles another way (see [What Gets Cleared Today](#what-gets-cleared-today)). Those never raise the price of a call.

## Vendors

| `vendor` value | The system |
|----------------|-----------|
| `cloudflare` | Cloudflare challenges and bot management |
| `sgcaptcha` | SiteGround's site check |
| `datadome` | DataDome |
| `perimeterx` | PerimeterX |
| `akamai` | Akamai Bot Manager |
| `incapsula` | Imperva Incapsula |
| `awswaf` | AWS WAF challenge |
| `ebay-splashui` | eBay's own challenge |
| `reddit` | Reddit's own check and refusal pages |
| `verify-challenge` | A site's own check page that sends you on once its check completes |
| `amazon` | Amazon's robot check |
| `hcaptcha` | hCaptcha |
| `recaptcha` | reCAPTCHA |
| `unknown` | No system was recognised. Only appears alongside `retry`, where the record exists to report the retry rather than a vendor. |

### What Gets Cleared Today

| Endpoint | Clears |
|----------|--------|
| Single, Proxy | `sgcaptcha`, `ebay-splashui`. Both are computational rather than visual, so no browser is involved. |
| Browser | `cloudflare`, `sgcaptcha` |

A few more are handled without a clear. Single and Proxy press Amazon's one-button robot check and report it as `retry: "amazon-continue"`, submit Reddit's light page check and report it as `retry: "reddit-js-check"`, and complete a site's own check page and report it as `retry: "verify-challenge"`. Browser waits up to 10 seconds for that same check page to send it on. Browser presses Amazon's button, and it waits while Akamai's sensor page, AWS WAF's challenge page, DataDome's device check or eBay's own challenge page loads the next page by itself, then returns that page. If that page never arrives, Browser returns the one it was holding, inside your `timeout_ms`. On Browser those names show in `defenses.present`, never in `cleared`, and the call costs 5.

Everything else on the list is recognised and reported, and nothing more. That split moves as FourA learns to clear more of them, so read `solved` rather than assuming from this table.

Two notes on the edges:

- `hcaptcha` and `recaptcha` are also ordinary form widgets. They're only reported when the response actually blocked you (403, 429, or 503), so a checkout page with a verification widget in a form doesn't report a defense.
- Being behind Cloudflare isn't a defense. `cloudflare` appears when there's a real challenge or bot-management artifact on the response, not because a site uses Cloudflare.

## Replaying a Clearance

`defense.cookie` is the whole point of the field. A clearance is bound to the exit that earned it and the User-Agent that earned it, so replay it through the same pair and the check doesn't run again.

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

The first call carries the cost of the clear. Every replay is an ordinary request at the ordinary price.

Three things break a replay:

1. **A different exit.** Pin the proxy ID the clearing response returned. See [Reuse a Proxy Across Requests](https://foura.ai/docs/how-to/reuse-a-proxy).
2. **A different User-Agent.** Browser responses return the `userAgent` they used. Send it back with the cookie.
3. **Expiry.** Clearances have their own lifetimes, set by the target. SiteGround's runs around 30 days for the whole site; a Cloudflare clearance is usually much shorter. Treat a clearance as a cache: when replays start returning challenges again, run one fresh call and take the new one.

## What It Costs

A cleared check changes the price on Browser only:

| Engine | Base | Cleared defense |
|--------|------|-----------------|
| Single | 1 (2 with `unblocker`) | No change |
| Proxy | 2 (4 with `unblocker`) | No change |
| Browser | 5 | 10 |

Browser charges 10 only when the solver was on and a system was genuinely cleared. A system that was recognised and not cleared costs 5, the same as a page with no check on it at all.

A check page or refusal page FourA recognises served with HTTP 200 (for example Amazon's robot check, Reddit's verification page or eBay's challenge page) isn't billed on any endpoint. Single, Proxy and Browser responses name it in `X-FourA-Check-Page`.

## Pair It With `validate`

`defense` tells you a check was met. `validate` tells FourA what the real page looks like, which is what lets a request fail rather than hand you an interstitial that happens to carry HTTP 200.

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

On `POST /api/auto/`, `validate` is what stops the ladder from accepting a challenge page and calling it done.

## Related

- [Protected sites](https://foura.ai/docs/guides/protected-sites): Which engine to reach for at each protection level
- [API Endpoints](https://foura.ai/docs/api/endpoints): Request and response reference for all four endpoints
- [Reuse a Proxy Across Requests](https://foura.ai/docs/how-to/reuse-a-proxy): Pin the exit a clearance is bound to
- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): How `meta.solved` fits into the ladder
- [Response Headers](https://foura.ai/docs/api/response-headers): Where the credit cost of a call shows up
