# FourA — Complete Documentation and Blog Content

> Full content export for AI assistants. Source: https://foura.ai
> For the index version, see https://foura.ai/llms.txt

## Pricing

Credit-based pricing. You only pay for successful requests. Failed requests, connection errors, and proxy retries are always free.

### Plans

| Plan | Price | Credits/month | API keys | Team | Premium traffic | Support |
|---|---|---|---|---|---|---|
| Free | Free | 3,000 | 1 | 1 | 0.1 GB | Community |
| Developer | $29/mo | 75,000 | 3 | 1 | 0.5 GB | Email |
| Startup | $99/mo | 450,000 | 10 | 5 | 5 GB | Priority |
| Business | $249/mo | 2,250,000 | 25 | 25 | 10 GB | Discord |

No credit card needed for Free. Annual billing saves 31 to 33% depending on the plan. Pricing page: https://foura.ai/prices

### Credit Costs

| Endpoint | Base | With add-on | Add-on |
|---|---|---|---|
| Single (one HTTP request) | 1 cr | 2 cr | Unblocker |
| Proxy Finder (auto-retries) | 5 cr | 10 cr | Unblocker |
| Browser (JavaScript-rendered pages) | 15 cr | 30 cr | a bot defense solved |

Auto costs the sum of the sub-calls it made and returns the session that worked, so the next request on that host can replay it through Single.

### Rate Limits

| Plan | Single conc | Single RPM | Proxy conc | Proxy RPM | Browser conc | Browser/day |
|---|---|---|---|---|---|---|
| Free | 3 | 30 | 2 | 10 | 1 | 30 |
| Developer | 10 | 120 | 5 | 30 | 1 | 100 |
| Startup | 25 | 300 | 15 | 100 | 2 | 300 |
| Business | 50 | 600 | 30 | 300 | 3 | 1000 |

### Features by Plan

| Feature | Free | Developer | Startup | Business |
|---|---|---|---|---|
| Unblocker | Yes | Yes | Yes | Yes |
| CAPTCHA Solver | Yes | Yes | Yes | Yes |
| Browser rendering | Yes | Yes | Yes | Yes |
| Premium exits | Yes | Yes | Yes | Yes |
| Geo-targeting | No | No | Yes | Yes |
| Webhook callbacks | No | No | Soon | Soon |
| Scheduled scraping | No | No | Soon | Soon |
| SLA | No | No | No | Yes |

Every response carries an X-FourA-Credits header with the cost of that call. When a plan ceiling stops a request, the response names the ceiling.

## Documentation

### Api

#### API Endpoints Reference
URL: https://foura.ai/docs/api/endpoints

A reference for all FourA API endpoints with request parameters and response formats.

## Base URL

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

## Authentication

Every request requires your API key in the `X-API-Key` header:

```bash
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"}'
```

Create and manage API keys in the [Dashboard](https://foura.ai/dashboard). Keys use the `pk_live_` prefix.

## Response Headers

Every response from `/api/*` carries two correlation headers:

| Header | Value | Description |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | Unique ID assigned to the request. Returned on every response, including 4xx and 5xx. Log it on your side. |
| `X-FourA-Credits` | integer | Credits spent on this request. Returned on success and on failure (the work was done either way). See [Request Outcomes](/docs/api/outcomes) for which outcomes are billable. |

The same request ID keys the request and response payload preview in the Dashboard's [Activity Log](/docs/dashboard/activity-log) (kept 24 hours, last 200 per key), so you can look up the exact request later and replay it from Activity straight into the [Playground](/docs/dashboard/playground). Include it when you contact support, and it pinpoints the request in seconds.

```bash
$ 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
...
```

See [Response Headers](/docs/api/response-headers) for the full list and usage tips.

## Endpoints

> **Using these endpoints via MCP?** The [`@fouradata/mcp` server](/docs/mcp/server) wraps all four endpoints as native MCP tools (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) with the same input shapes plus an `offload_large` opt-in for token-friendly large-response handling.

FourA provides four request endpoints, each optimized for a different scenario:

| Endpoint | Best for |
|----------|----------|
| `POST /auto/` | Smart fetch. You pass a URL, FourA picks the cheapest path that works (direct, rotated proxy, or browser) and remembers what works per host. |
| `POST /single/` | Fast HTTP requests, static pages, APIs |
| `POST /proxy/` | Protected sites with automatic proxy rotation, optional target-visible country scoping |
| `POST /browser/` | JavaScript-rendered pages, SPAs |
| `GET /profiles` | The browser-profile catalogue for `single` and `proxy`. Public, no API key. |

For a deeper walkthrough of when to pick each, see [Choosing the Right Endpoint](/docs/guides/choosing-task-type) and the [Smart Fetch guide](/docs/guides/smart-fetch).

## Target URL Restrictions

Targets that resolve to private, loopback, or reserved IP ranges (RFC 5735, RFC 6598, IPv6 reserved blocks) are refused with a 400 before the request leaves FourA. Only public hostnames and IPs are forwarded.

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

---

## Smart Fetch (Auto)

`POST /api/auto/`

You pass a URL plus optional `validate` rules. FourA walks a cost-aware ladder (cheap direct probe, rotated proxy, full browser) and stops at the first rung that returns a response your rules accept. On repeat calls to the same host, a warm session is replayed instead, so the second hit is cheap.

You don't tune retries, pool sizes, or proxy counts. FourA learns them per host.

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `url` | string | Yes | - | Target URL |
| `method` | string | No | `"GET"` | HTTP method |
| `headers` | [string, string][] | No | - | Custom headers as [name, value] pairs |
| `data` | any | No | - | Request body for non-GET requests |
| `validate` | object | No | - | Success criteria, same shape as Single Request's `validate` (see below). Tell auto what a real page looks like so it can tell content from a challenge page. |
| `returnSession` | boolean | No | `true` | Include the winning session (`proxy`, `cookies`, `userAgent`) in the response so you can replay it through `/api/single/` or `/api/browser/`. |
| `forceProxy` | boolean | No | `true` | Always route through a rotating proxy. Set `false` to allow the cheaper direct path when the target permits it (some defenses are stricter on proxy traffic). |
| `timeout_ms` | integer | No | `120000` | Total time budget for the whole call, in milliseconds. All sub-attempts run inside this budget. Min `5000`, max `180000`. |
| `ignoreProxies` | string[] | No | - | Proxy IDs to avoid on every sub-attempt. Use IDs returned by previous `/api/auto/` or `/api/proxy/` responses. |
| `followRedirects` | integer | No | `5` | Max redirects to follow on the cheap ladder rungs. `0` to disable. Max `20`. |

### Response

```json
{
  "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..."
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `status` | number | HTTP status from the target. |
| `data` | string or object | Response body. |
| `headers` | array or object | Target response headers. Single and proxy rungs return an array of per-hop header objects; browser rungs return a flat object. |
| `meta.rung` | string | Which ladder rung delivered the response. One of: `probe` (cheap direct request), `proxy` (rotating proxy), `browser` (full browser render), `cache` (warm session replayed), `warmup` (the site's entry page was fetched first and its cookies opened the deep URL), or `fail` (no rung produced an accepted response). |
| `meta.solved` | boolean | Whether a bot challenge was solved during this call. |
| `meta.attempts` | number | Sub-attempts made before success. |
| `meta.credits` | number | Total credits spent on this call. Matches `X-FourA-Credits`. |
| `session.proxy` | string | Encoded ID of the proxy that delivered the response. Reuse it on a Single or Browser request. Present when `returnSession` is `true`. |
| `session.cookies` | array | Cookies from the winning attempt. Present when `returnSession` is `true`. |
| `session.userAgent` | string | User-Agent used on the winning attempt. Present when `returnSession` is `true`. |
| `error` | string | Error message if the call failed. |

### Example

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

### Notes

- Auto is a coordinator. It calls Single, Proxy, or Browser internally and forwards your API key to each sub-call. Each sub-call appears in your [Activity Log](/docs/dashboard/activity-log); the outer `/api/auto/` call doesn't add a separate billable row.
- Pass `validate.data.accept` with a substring that only the real page contains. Without it, auto can't tell a real 200 from a challenge interstitial returned with status 200.
- `timeout_ms` caps the whole call. A cold first hit to a protected site can take tens of seconds; reused warm sessions usually finish in under a second.

---

## Single Request

`POST /api/single/`

Sends an HTTP request with realistic browser-like wire characteristics, without spinning up a real browser. This is the fastest endpoint.

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `method` | string | Yes | - | HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| `url` | string | Yes | - | Target URL. Use `{ts}` anywhere in the URL to insert the current timestamp for cache-busting. |
| `headers` | [string, string][] | No | - | Custom headers as [name, value] pairs |
| `unblocker` | boolean | No | `true` | Send realistic browser headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). On by default. Set `false` to send a plain client signature. |
| `timeout_ms` | number | No | 15000 | Overall timeout in ms (max: 120000) |
| `connect_timeout_ms` | number | No | 5000 | Connection timeout in ms |
| `accept_timeout_ms` | number | No | 5000 | Accept timeout in ms (time to wait for connection acceptance) |
| `server_response_timeout_ms` | number | No | 15000 | Server response timeout in ms (time to wait for first byte) |
| `dns_cache_timeout_sec` | number | No | 120 | DNS cache TTL in seconds (max: 240) |
| `followRedirects` | number | No | disabled | Max redirects to follow (0-20). Omit to disable. |
| `tryJsonData` | boolean | No | false | Parse response body as JSON if possible |
| `returnBuffer` | boolean | No | false | Return raw buffer instead of decoded string |
| `data` | any | No | - | Request body (string or object, auto-serialized to JSON) |
| `proxy` | string | No | - | Proxy ID from an earlier response, to pin the same exit. Pass the opaque string back verbatim. A raw proxy address is rejected with `400 Invalid proxy format`. Some IDs can't be pinned: see [Pinning an exit](#pinning-an-exit). |
| `browser` | string | No | Chrome | Browser to present: Chrome, Edge, Safari, Firefox, or Tor. See [Browser profiles](#browser-profiles). |
| `os` | string | No | - | Operating system to present: Windows, macOS, Android, or iOS. A family name accepts any of its versions. |
| `version` | string | No | newest | Browser version to present, as listed in the catalogue. The newest match wins when several fit. |
| `profile` | string | No | - | Exact profile id from `GET /api/profiles`, instead of the three fields above. |
| `validate` | object | No | - | Response validation rules (see below) |

### Browser profiles

By default a request presents the latest Google Chrome. Some targets accept one browser and refuse another, so `browser`, `os`, and `version` narrow a catalogue of measured profiles, and `profile` selects one by id.

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

Rules:

- Selection requires `unblocker` (on by default). With the unblocker off no browser headers are sent, so the request is refused rather than half-applied.
- When several profiles match, the newest version wins.
- A combination the catalogue can't present returns an error naming what is available. The request is never sent as a different browser.
- The same four fields are available inside the `request` object of `POST /proxy/`.

`GET /api/profiles` returns the full catalogue and needs no API key:

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

`osFamily` is the value to filter on when building a picker; `os` keeps the release name for display.

### Validation Rules

The `validate` object lets you define conditions for success and failure. If a `fail` condition matches, the request is treated as failed. If `accept` conditions are set, only matching responses are treated as successful.

```json
{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `validate.status.accept` | number[] | HTTP status codes to accept |
| `validate.status.fail` | number[] | HTTP status codes to reject |
| `validate.headers.accept` | object | Header key-value pairs that must be present |
| `validate.headers.fail` | object | Header key-value pairs that trigger failure |
| `validate.data.accept` | string[] | Strings that must appear in the response body |
| `validate.data.fail` | string[] | Strings in the response body that trigger failure |

### Example

```bash
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:

```json
{
  "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,
  "proxy": "A1B2C3"
}
```

When the target runs a bot check on the way to the body, the response also carries a `defense` object naming the vendor and whether the check was cleared:

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

| Field | Type | Description |
|-------|------|-------------|
| `status` | number | HTTP status code from the target |
| `headers` | array | One object per redirect hop. Each has a `result` field with the status line plus every response header. Multi-value headers (`Set-Cookie`, `Link`, `WWW-Authenticate`) come back as arrays of strings. |
| `data` | string/object | Response body (JSON if `tryJsonData` is true) |
| `total_time` | number | Total request time in seconds |
| `proxy` | string | Encoded ID of the proxy the request went through (only when a `proxy` was supplied on the request). Reuse it on a follow-up call to pin the same exit. |
| `defense` | object | Present when the target ran a bot check on this request, or when a retry with the site's own cookies produced the body. `defense.solved` says whether a check was cleared, `defense.retry` says whether a retry got you the content. See [Anti-Bot Defenses](/docs/api/anti-bot-defenses) for every field and the full vendor list. |
| `error` | string | Error message if the request failed |

---

## Proxy Request

`POST /api/proxy/`

Routes your request through rotating proxies with automatic retry on failure. Optionally scope selection to a set of target-visible exit countries.

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `request` | object | Yes | - | A single request body (same fields as Single Request above) |
| `timeout_ms` | number | No | 45000 | Overall timeout for all attempts in ms (max: 120000) |
| `maxTries` | number | No | 5 | Maximum proxy rotation attempts (max: 90) |
| `ignoreProxies` | string[] | No | - | Proxy IDs to exclude from rotation (use IDs returned by previous responses) |
| `exitCountries` | string[] | No | - | Strict allowlist of two-letter target-visible country codes (e.g. `["CZ", "GB"]`). Values are trimmed, uppercased, and deduplicated. Proxies with unknown exits are excluded and the request never falls back to an unrequested country. |
| `exitClass` | string | No | - | `standard` or `premium`. `premium` lets the request escalate to a premium exit when the standard pool is struggling on a protected target. Requires a plan that includes premium exits. |

### exitCountries scoping

Selection uses the latest available target-visible country metadata, normally refreshed within about ten minutes. It's not a live geolocation lookup during the request. Don't infer the serving country from the proxy host address.

If the current pool has no match for the requested countries, the response returns HTTP 200 with an error envelope:

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

Preserve the requested scope and retry later. Change or widen it only when your workflow's country requirement explicitly changes.

### Example

```bash
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:

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

| Field | Type | Description |
|-------|------|-------------|
| `proxy` | string | Encoded identifier of the proxy used. Reuse it on a Single or Browser request by passing it as the `proxy` field, or skip it on the next Proxy request via `ignoreProxies`. |
| `exitCountry` | string | Two-letter target-visible country code of the proxy that served the request. Present only when the request set `exitCountries`. Always verify it's one of the codes you requested before trusting the response. |
| `exitClass` | string | Which class of exit served this request, present only when the request named one. `premium` means a premium exit returned the body; `standard` means the standard pool did. |
| `total` | number | Outer wall-clock duration in seconds (float). Includes proxy selection, retries, and the successful attempt. `total_time` is the inner request only; `total` is always >= `total_time`. |
| `profile` | string | The browser profile the rotation chose, present **only** when it wasn't the one you asked for. Absent means the request went out exactly as written. Pass the id back as `profile` on follow-up calls to keep the browser that worked. |
| `error` | string | Error message if the request failed. On a scope miss, `code` is `no_eligible_proxy` and `details.exitCountries` echoes the normalized scope. |
| `attemptReport` | object | Present on **every** failed Proxy call. Counts what the attempts ran into, so a blocked pool, a dead pool, and a `validate` rule that never matched don't all read as the same error. See below. |

All Single Request response fields are also included, `defense` among them: a proxy attempt that met a bot check reports it the same way Single does.

### Why a Proxy Call Failed

`Download maxTry limit reached` reads the same whichever way the attempts went, so every failed Proxy response carries an `attemptReport` beside the error:

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

| Field | Type | Description |
|-------|------|-------------|
| `total` | integer | Attempts made |
| `noResponse` | integer | The exit never answered, so the site was never reached |
| `defense` | integer | The site answered and a bot check was recognised on that answer |
| `contentRejected` | integer | HTTP 200, no bot check, rejected only by your `validate.data` |
| `statusRejected` | integer | The site answered, no bot check, rejected by your `validate.status` |
| `other` | integer | Answered, and none of the above |
| `vendors` | string[] | Bot-check vendors recognised anywhere in the task |
| `profilesTried` | string[] | Browser profiles the task sent, in first-use order. `default` means your request went out untouched. |
| `summary` | string | One sentence built from the counts, safe to log |

The `error` string is unchanged, so a client matching on it keeps working. What to do about each count: [Why a Proxy Request Ran Out of Tries](/docs/troubleshooting/proxy-attempt-report).

### exitClass

Some targets refuse the exits in the standard pool no matter how many are tried. `exitClass: premium` tells Proxy it may escalate such a request to a **premium exit** in addition to the standard pool, instead of only rotating within it.

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

Three things are worth knowing before you send it.

**It is an allowance, not an instruction.** The standard pool still races for the answer, and it usually wins. A premium exit joins only when the pool has spent a short budget on the request or the target has visibly refused it. A request that the standard pool answers first is a normal success and costs you no premium traffic.

**The response tells you what actually served you.** When you name a class, the response carries `exitClass` back:

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

`premium` means a premium exit returned the body. `standard` means the standard pool did, which is the answer you also get when a premium exit could not be obtained, and when the premium traffic included in your plan (plus anything you bought on top) is spent for the billing period. Neither is an error, and you can reconcile your premium traffic against these per request rather than against a monthly figure. The same value travels in the `X-FourA-Exit-Class` response header (see [Response Headers](/docs/api/response-headers#x-foura-exit-class)).

**Premium traffic is measured separately.** The bytes of a request served by a premium exit count towards premium bandwidth as well as your total bandwidth; the same bytes, reported twice, never added together. Your [Usage & Limits](/docs/dashboard/quota) page shows total traffic, the premium share of it, and the premium allowance you're measured against.

Omitting the field is not the same as sending `standard`. Omitting it leaves the decision unstated; sending `standard` says explicitly that this request must never escalate, which is the way to keep a particular job off premium traffic entirely.

**Running out is not an error.** A request naming `premium` after the allowance is spent keeps working: the standard pool serves it and the response says `standard`. No job stops over a spent allowance.

`exitClass: premium` needs a plan that includes premium exits. On a plan without them, the request never spends a premium exit: it's either refused with a 403 carrying `X-FourA-Limit: plan_limit_premium` (see [Rate Limits](/docs/api/rate-limits#plan-limits)), or served from the standard pool with `exitClass: standard` in the response. Handle both.


### Browser Profile Rotation

Proxy rotates exits. When a site refuses the browser FourA presented rather than the exit it came from, Proxy also moves to another browser family from the catalogue. It adds no attempt: the rotation changes what a retry sends, never whether one happens.

An explicit `profile`, `browser`, `os`, or `version` on your inner `request` is never overridden, and neither is a request that carries its own `User-Agent` or `Cookie` header, because a clearance is bound to the signature that earned it.

---

## Browser Request

`POST /api/browser/`

Opens your URL in a Chrome browser instance. The page loads, JavaScript executes, and you get the fully rendered HTML plus the cookie jar.

### Request Body

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `url` | string | Yes | - | Target URL |
| `headers` | object | No | - | Custom headers as key-value pairs |
| `cookies` | array | No | - | Cookies to set: `[{name, value, domain?}]` |
| `userAgent` | string | No | - | Custom User-Agent string |
| `unblocker` | boolean | No | `true` | Auto-solve common bot challenges (Cloudflare clearance, similar gates) during page load. On by default. Set `false` to render whatever the page returns, including a challenge page, without solving. |
| `proxy` | string | No | - | Proxy ID from an earlier response, to pin the same exit. Pass the opaque string back verbatim. A raw proxy address is rejected with `400 Invalid proxy format`. |
| `exitCountry` | string | No | - | Two-letter country code (ISO 3166-1 alpha-2) of the country the request leaves by. Sets the browser's clock to a timezone that matches. See [Matching the browser clock to the exit](#matching-the-browser-clock-to-the-exit). |
| `timeout_ms` | number | No | 30000 | Page load timeout in ms (max: 120000) |
| `checkStatus` | number | No | - | Expected HTTP status (request fails if different) |
| `checkText` | string | No | - | Text that must appear in the rendered page |

### Matching the browser clock to the exit

A page can read the browser's timezone and compare it against the country of the IP it sees. A mismatch is one of the cheapest signals a bot detector has, and it costs you nothing to remove.

Set `exitCountry` to the country your traffic leaves by and the browser reports a timezone that belongs to it:

```json
{
  "url": "https://example.com",
  "proxy": "A1B2C3",
  "exitCountry": "BR"
}
```

Rules:

- The value is the **exit** country, meaning the country the target sees, not where the proxy is hosted. The two disagree often enough to matter.
- Omit it and FourA uses the exit country when it knows one, and otherwise leaves the browser clock alone rather than guessing.
- A country code FourA doesn't recognise is treated the same as leaving the field out. It isn't an error.
- Only the clock follows the country. `Accept-Language` and the content the site serves are untouched, so a page won't switch languages on you.

### The `userAgent` parameter

Send `userAgent` and that exact string is what the page, its workers, and the target all see. FourA also derives the matching client hints from it (`sec-ch-ua`, `sec-ch-ua-platform`, `navigator.platform`, and the high-entropy values a detector asks for by name), so the request doesn't claim one browser in the header and another in JavaScript.

The `userAgent` in the response is the one that was presented. That matters when you replay a clearance: a `cf_clearance` cookie is bound to the exit and the User-Agent that earned it, so send back the string the response reported, not the one you think was used. See [Anti-Bot Defenses](/docs/api/anti-bot-defenses).

Send a non-Chromium string (a Firefox User-Agent, say) and it's presented as-is, with no Chromium brand list attached.

### Example

```bash
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:

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

| Field | Type | Description |
|-------|------|-------------|
| `status` | number | HTTP status code from the target |
| `headers` | object | Response headers |
| `body` | string or object | Fully rendered page content. String HTML when content-type is HTML; object when the page returned JSON and was auto-parsed. |
| `cookies` | array | Full cookie objects from the page. Each cookie includes `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite`, and other cookie properties. |
| `userAgent` | string | Browser User-Agent used |
| `defenseSolved` | boolean | `true` if a bot defense was met and genuinely cleared on this call. Absent otherwise. Drives the 15 vs 30 credit cost. |
| `defenses` | object | `present` lists every vendor recognised during the page load, `cleared` lists the ones whose clearance the final page holds. A vendor can appear in `present` and never in `cleared`. See [Anti-Bot Defenses](/docs/api/anti-bot-defenses). |
| `proxy` | string | Encoded ID of the proxy the request went through (only when a `proxy` was supplied on the request). Reuse it on follow-up calls to keep the same exit. |
| `error` | string | Error message if the request failed |

---

## Pinning an Exit

A `proxy` value on a Single or Browser request pins the exit a previous call used. Pass back the opaque ID exactly as it came, never a proxy address.

Two IDs are refused, both with a 400:

| Error | Meaning |
|-------|---------|
| `Invalid proxy format` | The value isn't an ID FourA issued. A raw proxy address lands here. |
| `Proxy not found` | The ID decoded, but it no longer resolves to a live exit. Take a fresh one from a new call. |
| `Managed exit: this proxy id cannot be pinned to a request` | The exit exists, but it isn't one FourA will hold open for a named request. A premium exit's ID lands here when your plan has no premium traffic left to spend. Reuse the session it came back on, or run the call through `POST /api/proxy/` and take whichever exit it picks. |

A pinned premium exit is metered as premium traffic. The response carries `X-FourA-Exit-Class: premium` so you can see it per request, and the bytes count toward the premium traffic on your [Usage & Limits](/docs/dashboard/quota) page as well as toward your total bandwidth. Pinning needs premium exits in your plan and allowance left; otherwise the ID is refused with the managed-exit 400 above.

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 | Request completed (check inner `status` for target response) |
| 400 | Invalid request body, parameters, target IP in a private/reserved range, or a proxy ID that can't be pinned |
| 401 | Missing or invalid API key |
| 403 | The endpoint or a parameter isn't in your plan. `X-FourA-Limit` names it: `plan_limit_feature` or `plan_limit_premium`. |
| 429 | A plan limit (`X-FourA-Limit` set) or the platform's shared per-minute allowance (no header) |
| 500 | Internal server error |
| 502 | `Upstream unavailable`. FourA reached its engine but the reply was unusable. Retry. |
| 503 | Service temporarily disabled or at capacity, or `Backend service unavailable` while an engine restarts |
| 504 | `Upstream timeout`. The engine didn't finish inside the time budget for this request. Raise `timeout_ms` or retry. |

## Next Steps

- [Smart Fetch (Auto)](/docs/guides/smart-fetch): When to let FourA pick the path for you
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): When to pick Single, Proxy, or Browser by hand
- [Authentication](/docs/getting-started/authentication): Manage your API keys
- [Error Handling](/docs/api/errors): Handle errors gracefully
- [Anti-Bot Defenses](/docs/api/anti-bot-defenses): Read the `defense` field and replay a clearance
- [Why a Proxy Request Ran Out of Tries](/docs/troubleshooting/proxy-attempt-report): Read `attemptReport` and act on it
- [Rate Limits](/docs/api/rate-limits): Understand request limits
- [Quick Start](/docs/getting-started/quick-start): Your first request in 30 seconds

---

#### API Errors
URL: https://foura.ai/docs/api/errors

How to handle errors from the FourA API.

## Error Response Format

The API returns flat JSON objects for all errors. There's no nested `error` object or error codes.

```json
{
  "error": "Invalid API key"
}
```

Some errors include extra fields like `status`, `service`, `retryAfter`, `current`, or `limits` at the top level:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

## Tracking a Request

Every API response (success or error) includes an `X-FourA-Request-Id` header with a UUID for that call. Log it on your side. If you need to ask support what happened to a specific request, that ID lets us find it.

```bash
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/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...
```

## Error Types

### 400: Bad Request

The request body is missing required fields, contains invalid values, or names a target the API refuses to fetch.

```json
{
  "error": "Invalid request body format"
}
```

The same 400 also covers SSRF protection. If your `url` resolves to a private, loopback, or otherwise reserved IP range (RFC 5735, RFC 6598, IPv6 reserved blocks), the request is rejected before it leaves FourA's network:

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

Malformed JSON in the body is refused the same way, before any field is read:

```json
{
  "error": "Invalid JSON in request body"
}
```

The `proxy` and `ignoreProxies` fields have their own 400s. Both take the opaque proxy IDs earlier responses returned, so anything else fails to decode:

| Message | What happened |
|---------|---------------|
| `Invalid proxy format` | The `proxy` value isn't a proxy ID FourA issued. A raw proxy address lands here. |
| `Invalid ignoreProxies format` | One of the entries in `ignoreProxies` isn't a proxy ID. |
| `Proxy not found` | The ID decoded cleanly but no longer resolves to a live exit. Pick a fresh one. |
| `Managed exit: this proxy id cannot be pinned to a request` | The exit is real, but it isn't one FourA will hold open for a named request. A premium exit's ID lands here when your plan has no premium traffic left to spend. Reuse the session it came back on, or run the call through `POST /api/proxy/` and take whichever exit it picks. |

**Fix:** Check that your request includes all required fields, that URLs use `http://` or `https://`, that the host resolves to a public address, and that any `proxy` value is an ID copied verbatim from an earlier response.

These are `client_error` outcomes: the request never left FourA, so nothing was spent on your behalf.

### 401: Unauthorized

Your API key is missing or invalid.

Missing key:

```json
{
  "error": "Missing API key. Include X-API-Key header."
}
```

Invalid key:

```json
{
  "error": "Invalid API key"
}
```

**Fix:** Verify your `X-API-Key` header contains a valid key. Generate a new key from the [Dashboard](https://foura.ai/dashboard) if needed.

### 403: Not in Your Plan

The call asked for an endpoint or a parameter your plan doesn't include. The response sets `X-FourA-Limit` and puts the same code in the body under `reason`:

```json
{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

`reason` is `plan_limit_feature` for an endpoint the plan excludes or for `exitCountries` on a plan without geo targeting, and `plan_limit_premium` for `exitClass: premium` on a plan without premium exits. The `error` string names the endpoint or parameter.

A 403 from FourA is never about the target site: the target was never contacted. A 403 the target returned arrives as HTTP 200 with `status: 403` inside the body.

**Fix:** Remove the parameter, call an endpoint your plan includes, or upgrade. No `Retry-After` is set, because waiting doesn't change the answer. Nothing was spent: the outcome is `rate_limit`, and only `success` is billed.

### 429: Rate Limited

Two different checks answer with 429, and they don't carry the same fields.

**Your plan's own limits.** The response sets an `X-FourA-Limit` header naming which limit refused the call and puts the same code in the body under `reason`:

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

`reason` is one of `plan_limit_concurrency`, `plan_limit_rate`, `plan_limit_browser_daily`, `plan_limit_credits`, or `plan_limit_bandwidth`. When a wait helps, the wait lives in `retry_after_seconds` and in the `Retry-After` header, never in `retryAfter`. `plan_limit_browser_daily` carries neither, because the allowance comes back at midnight UTC and not in seconds. Nothing was spent: the outcome is `rate_limit`, and only `success` is billed.

**The platform's shared allowance.** No `X-FourA-Limit` header, and the wait is in `retryAfter`:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`current` and `limits` describe the service across all traffic, not your account. A refusal here means FourA is busy.

**Fix:** Wait whichever of `Retry-After`, `retry_after_seconds`, or `retryAfter` the response carries. On a concurrency or rate limit, cap how many requests you keep open rather than re-sending the refused batch. On a daily or billing-period limit, stop the run. See [Rate Limits](/docs/api/rate-limits) for every field and [Run Requests in Parallel](/docs/how-to/run-requests-in-parallel) for the pattern.

### 500: Server Error

Something went wrong on our side.

**Fix:** Retry the request after a short delay. If the error persists, check the [status page](https://updates.foura.ai/status) or contact support with the `X-FourA-Request-Id` from the failed response.

### 502: Upstream Unavailable

FourA reached its own engine but couldn't use the reply.

```json
{
  "error": "Upstream unavailable",
  "details": "..."
}
```

**Fix:** Retry with a short backoff. This is on our side, so it costs you nothing: the outcome is `service_error` and only `success` is billed.

### 504: Upstream Timeout

The engine didn't finish inside the time budget for this request.

```json
{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}
```

A 504 is about how long the work took, not about your key, your parameters, or your proxy. Slow targets, cold challenge solves, and big pages are the usual causes.

**Fix:** Raise `timeout_ms` on the request (Single accepts up to 120000, Browser up to 120000, Auto up to 180000), or retry. FourA waits for the budget you declared plus a small margin, so asking for more time genuinely buys more time.

### 503: Service Disabled or At Capacity

A 503 means either the service is temporarily unavailable for maintenance or the platform's concurrency allowance is full. Both forms carry the same keys: `error`, `status`, `service`, `retryAfter`, `current`, and `limits`. Tell them apart by the `error` string, not by which fields are present.

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`Service disabled` is maintenance and `current` reads `0` for both counters, because the request was turned away before anything was measured. `Service at capacity` is the concurrency form, and there `current` holds the platform's real usage. See [Rate Limits](/docs/api/rate-limits) for that shape.

**Fix:** Wait `retryAfter` seconds, then retry. The status page lists active maintenance windows.

A third 503 shape has no `retryAfter`. It means the engine behind your endpoint was restarting when your call arrived:

```json
{
  "error": "Backend service unavailable",
  "backend_status": 503
}
```

Retry after a second or two.

## Reading Failures from `/api/auto/`

`POST /api/auto/` answers with HTTP 200 whenever the ladder ran, even when every rung failed. The real outcome lives in the body:

```json
{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
```

So don't branch on the transport status for Auto. Read `status` and `error` from the body instead. A genuine non-200 from `/api/auto/` means FourA rejected the call before the ladder started: 401, 400, 429, or 503, all documented above.

A plan limit met by one of the sub-calls also comes back as HTTP 200. The body is the refusal itself, with its `reason`, plus `status` and `meta`:

```json
{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

Which limits stop the ladder and which only close a rung is covered in [Smart Fetch (Auto)](/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder).

## Target-Side Failures Inside 200 OK

Not every failure shows up as a non-2xx HTTP status. When the target site returns HTTP 200 with an error payload, FourA still hands you the body but classifies the request as `application_error`. When the target returns a non-2xx your `validate` rules don't accept, the outcome is `application_fail` and the body comes through unchanged.

Both cases are billable as if the request worked at the wire level. The [Outcomes](/docs/api/outcomes) reference covers the full taxonomy.

## Response Encoding

FourA auto-decodes response bodies to UTF-8. If the target serves `windows-1251`, `gbk`, `shift_jis`, `iso-8859-*`, or any other charset declared in the `Content-Type` header or an HTML `<meta charset>` tag, you receive a clean UTF-8 string in the `data` (single, proxy) or `body` (browser) field.

For binary payloads (images, protobuf, raw audio), set `returnBuffer: true` on the request. The body comes back as a base64 buffer with no charset transcoding applied.

## Retry Strategy

A practical retry policy:

```python
import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")
```

## Proxy Failures Carry a Report

A `POST /api/proxy/` call that runs out of attempts comes back as HTTP 200 with an error envelope, not as an HTTP error code. The error string is short and always the same shape, so an `attemptReport` object rides beside it with the counts:

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

Log `attemptReport.summary` next to the error and you'll know whether the exits were blocked, dead, or delivering pages your own `validate` rules rejected. Field reference and what to do about each count: [Why a Proxy Request Ran Out of Tries](/docs/troubleshooting/proxy-attempt-report).

## Related

- [Rate Limits](/docs/api/rate-limits): Plan limits, concurrency, and RPM details
- [Run Requests in Parallel](/docs/how-to/run-requests-in-parallel): Staying under your plan's concurrency
- [Request Outcomes](/docs/api/outcomes): The seven outcome values explained
- [Common Issues](/docs/troubleshooting/common-issues): Symptoms, causes, fixes
- [Anti-Bot Defenses](/docs/api/anti-bot-defenses): When the body is a challenge page rather than an error
- [Why a Proxy Request Ran Out of Tries](/docs/troubleshooting/proxy-attempt-report): Reading `attemptReport`

---

#### Rate Limits
URL: https://foura.ai/docs/api/rate-limits

Every FourA API request passes three checks before it reaches an engine: the platform's shared allowance for all traffic, the platform's shared allowance for the endpoint you called, and then the limits of your own plan. Each check can refuse a request on its own, and each one answers with a different body.

## The Three Checks, in Order

1. **Global platform limit.** Everything the API host you called is handling at that moment, whichever endpoint the traffic went to. A refusal here reports `"service": "api"`.
2. **Per-endpoint platform limit.** Traffic on the single, proxy, or browser service you called.
3. **Plan limits.** What your own plan allows: which endpoints and parameters it includes, how many requests may run at once per endpoint, how many per minute, how many browser requests per day, and the credits and bandwidth available in the billing period.

Checks 1 and 2 count FourA's total traffic, not yours. Read a refusal from either one as "FourA is busy", not as "you sent too much". Check 3 is about your account alone, and nothing else on the platform moves it.

`POST /api/auto/` isn't measured on its own. The Single, Proxy and Browser sub-calls it makes for you pass all three checks like any other request, so a parallel batch of auto calls counts against your plan through its sub-calls.

## Plan Limits

A plan limit answers with an `X-FourA-Limit` header naming which limit refused the call. The same code is in the body under `reason`, so you can branch on it without reading headers. Every plan-limit body carries `error`, `reason`, and `documentation`; the rest of the fields depend on the limit.

| `X-FourA-Limit` | Status | What ran out |
|-----------------|--------|--------------|
| `plan_limit_feature` | 403 | The endpoint you called, or the `exitCountries` parameter, isn't in your plan |
| `plan_limit_premium` | 403 | `exitClass: premium` isn't in your plan |
| `plan_limit_concurrency` | 429 | Simultaneous requests on that endpoint |
| `plan_limit_rate` | 429 | Requests per minute on that endpoint |
| `plan_limit_browser_daily` | 429 | Browser requests for the day |
| `plan_limit_credits` | 429 | Billed credits for the billing period |
| `plan_limit_bandwidth` | 429 | Bandwidth for the billing period |

The numbers behind each limit are your plan's, and the **Limits & Features** tab of [Usage & Limits](/docs/dashboard/quota) lists them next to your live usage. Don't hardcode them: every refusal carries the ceiling that refused it.

A refused request spends nothing. The outcome is `rate_limit`, and only `success` is billed.

### Endpoint or parameter not in the plan

A 403 with `plan_limit_feature` means the call asked for something the plan doesn't include. The check runs before anything is counted, so the refused call doesn't touch your rate or daily counters.

```json
{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

The same code and status answer a `POST /api/proxy/` call that sets `exitCountries` on a plan without geo targeting. The `error` string names the parameter:

```json
{
  "error": "Geo targeting (the exitCountries parameter) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

`plan_limit_premium` is the same shape for `exitClass: premium` on a plan without premium exits. FourA may instead serve such a request from the standard pool and report `exitClass: standard` in the response, so handle both answers. Neither one spends a premium exit. See [exitClass](/docs/api/endpoints#exitclass).

Neither 403 sets `Retry-After`. Waiting doesn't change the answer.

### Simultaneous requests

Concurrency is counted per endpoint: your plan carries one ceiling for Single, one for Proxy, and one for Browser. The request that goes over comes back as 429 with `Retry-After: 1`:

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

`in_flight` counts the refused request too, so it reads at least one more than `limit`.

The fix is to bound your own parallelism rather than to retry harder. Answering a 429 by re-sending the same batch immediately produces another 429 for every call in it. See [Run Requests in Parallel](/docs/how-to/run-requests-in-parallel) for a worked pattern.

### Requests per minute

Single and Proxy carry a per-minute allowance, measured over a sliding minute. Refused requests count toward that minute too, so hammering during a cooldown doesn't shorten it.

```json
{
  "error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 613,
  "retry_after_seconds": 17
}
```

`retry_after_seconds` runs to the end of the current minute. The `Retry-After` header carries the same value.

### Browser requests per day

Browser has no per-minute allowance. Its plan limit is a number of browser requests per day, counted from midnight UTC, and the meter counts every browser request admitted, not only successful ones.

```json
{
  "error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
  "reason": "plan_limit_browser_daily",
  "documentation": "https://foura.ai/prices",
  "limit_per_day": 300,
  "used_today": 301
}
```

This refusal carries no `retry_after_seconds` and no `Retry-After` header, because the wait is hours rather than seconds. Treat it as a stop and schedule the next run for midnight UTC.

### Credits for the billing period

Only billed credits count, which means only successful requests. When the billed total reaches the credits available to you this period, further requests are refused until the period resets or you buy more.

```json
{
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}
```

`hard_stop` is the billed-credit count at which requests stop for this period. Read it from the body rather than computing it: it already includes any credits you bought on top of the plan.

### Bandwidth for the billing period

Plans that carry a bandwidth cap refuse requests once the bytes transferred this period reach it. Bought bandwidth counts the same as included bandwidth, and the `error` string quotes what's available to you, not what the plan alone includes.

```json
{
  "error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
  "reason": "plan_limit_bandwidth",
  "documentation": "https://foura.ai/prices",
  "used_bytes": 53687091200,
  "limit_bytes": 53687091200,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}
```

On both period limits, `retry_after_seconds` is capped at 24 hours; `resets_at` is the exact instant the period rolls over.

### Plan limit fields

| Field | Type | Present on | Description |
|-------|------|-----------|-------------|
| `error` | string | all | Human-readable message, including the number you're held to |
| `reason` | string | all | `plan_limit_` plus the limit name. Same value as the `X-FourA-Limit` header. |
| `documentation` | string | all | Link to the plans page |
| `retry_after_seconds` | number | concurrency, rate, credits, bandwidth | How long to wait. Same value as the `Retry-After` header. |
| `limit` | number | concurrency | Simultaneous requests the plan allows on that endpoint |
| `in_flight` | number | concurrency | Requests running on that endpoint for your account, including the refused one |
| `limit_per_minute` | number | rate | Requests per minute the plan allows on that endpoint |
| `current_rate` | number | rate | Requests counted in the sliding minute, including the refused one |
| `limit_per_day` | number | browser daily | Browser requests the plan allows per day |
| `used_today` | number | browser daily | Browser requests counted today, including the refused one |
| `used` | number | credits | Billed credits so far this period |
| `hard_stop` | number | credits | Billed credits at which requests stop this period |
| `used_bytes` | number | bandwidth | Bytes transferred so far this period |
| `limit_bytes` | number | bandwidth | Bytes available this period |
| `resets_at` | string | credits, bandwidth | ISO 8601 timestamp of the period end |

Plan limits use `retry_after_seconds`. The platform limits below use `retryAfter`. A retry helper needs to read both, or read the `Retry-After` header, which only plan limits set.

## Platform Limits

The platform checks track two things per service and one more across all of them:

- **Concurrency**: how many requests FourA is running at the same time.
- **RPM**: how many requests FourA has taken in the last 60 seconds.

Both counters are shared by everyone using that service. `current` and `limits` in the responses below describe the platform, not your account. If you want your own number, read `in_flight` from a plan-limit response, or open **Usage & Limits** in the [dashboard](https://foura.ai/dashboard).

### 429: RPM Exceeded

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}
```

The service took its allowed requests for the last minute. Wait `retryAfter` seconds.

### 503: Concurrency Exceeded

```json
{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}
```

The service is running as many requests as it's allowed to run at once. This clears in seconds.

## Service Disabled

When a service is temporarily taken offline for maintenance, the API returns 503 with a different error message:

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

This isn't a rate limit. The service is temporarily unavailable. Check the `retryAfter` value and retry after that many seconds. This typically resolves within minutes.

Both 503 shapes carry the same keys, so branch on the `error` string and never on which fields are present. `Service disabled` is maintenance, `Service at capacity` is concurrency.

On the maintenance shape, `current.concurrency` and `current.rpm` are always `0`: the request was turned away before anything was measured.

## Platform Limit Fields

| Field | Type | Description |
|-------|------|-------------|
| `error` | string | Human-readable error message |
| `status` | number | HTTP status code (429 or 503) |
| `service` | string | Which service refused the call: single, proxy, browser, or api |
| `retryAfter` | number | Recommended wait time in seconds before retrying |
| `current.concurrency` | number | Requests the service was running platform-wide when it refused |
| `current.rpm` | number | Requests the service took platform-wide in the last 60 seconds |
| `limits.maxConcurrency` | number | The service's platform-wide concurrency allowance |
| `limits.maxRpm` | number | The service's platform-wide per-minute allowance |

## Handling Every Refusal With One Helper

`Retry-After` is set on the plan limits that are worth waiting for, `retry_after_seconds` is in their bodies, and `retryAfter` is in the platform bodies. Read all three in that order, and stop on the plan limits that no wait will clear:

```python
import time
import requests

# Plan limits that a short wait never clears.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def wait_seconds(resp, attempt):
    header = resp.headers.get("Retry-After")
    if header and header.isdigit():
        return int(header)
    try:
        body = resp.json()
    except ValueError:
        return 2 ** attempt
    return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt

def fetch(url, api_key, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json={"method": "GET", "url": url},
        )

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")

        if resp.status_code in (429, 503):
            time.sleep(wait_seconds(resp, attempt))
            continue

        return resp

    raise RuntimeError("Max retries exceeded")
```

A daily allowance doesn't come back for hours, and a period allowance doesn't come back for days, so treat them as a stop rather than a wait. Read `resets_at` from the body if you want to schedule the next run.

## Tips

- Cap the number of requests you keep in flight instead of retrying a refused batch. A retry storm turns one 429 into many.
- Read `X-FourA-Limit` first. It tells you in one string whether the limit is yours or the platform's, and no platform refusal sets it.
- Don't hardcode the numbers. Every plan-limit response carries the ceiling that refused it, and [Usage & Limits](/docs/dashboard/quota) shows all of them.
- `retryAfter` on platform limits is fixed by kind: 2 seconds for concurrency, 5 for RPM, 60 for maintenance.
- Match on `error` to tell the two 503s apart. Both shapes carry `current` and `limits`, so a check for "are those fields there?" reads maintenance as a concurrency problem.
- A 403 with `X-FourA-Limit` is about your plan, not about the target site. The target never answered.

## Related

- [Run Requests in Parallel](/docs/how-to/run-requests-in-parallel): A worked bounded-concurrency pattern
- [Usage & Limits](/docs/dashboard/quota): Every plan limit next to your live usage
- [API Endpoints](/docs/api/endpoints): Full parameter reference
- [Error Handling](/docs/api/errors): All error types and responses
- [Response Headers](/docs/api/response-headers): `X-FourA-Limit`, `Retry-After`, and the rest
- [Troubleshooting](/docs/troubleshooting/common-issues): Common problems and fixes

---

#### Inspect Endpoint
URL: https://foura.ai/docs/api/inspect

A public diagnostic endpoint that returns your client IP and proxy detection details. Use it to verify whether your outbound traffic is going through a proxy before you start sending requests through FourA.

## Request

`GET /inspect`

This endpoint is public. No API key, no `X-API-Key` header.

```bash
curl https://eu.api.foura.ai/inspect
```

## Response

```json
{
  "clientIp": "203.0.113.42",
  "proxyDetection": {
    "isProxy": false,
    "proxyType": "none",
    "anonymityLevel": "none",
    "confidence": "medium",
    "detectedHeaders": [],
    "explanation": "Direct connection (no client-side proxy detected). Note: Elite proxies cannot be ruled out without additional data."
  },
  "proxyChain": {
    "originalClientIp": "203.0.113.42",
    "proxyCount": 0,
    "hasPrivateIps": false
  },
  "timestamp": "2026-04-29T08:07:04.683Z"
}
```

### Top-Level Fields

| Field | Type | Description |
|-------|------|-------------|
| `clientIp` | string | Original client IP (leftmost address in the forwarded chain) |
| `proxyDetection` | object | Proxy detection and anonymity analysis |
| `proxyChain` | object | Client-side IP chain breakdown |
| `timestamp` | string | ISO 8601 timestamp of when the request was inspected |

### `proxyDetection`

| Field | Type | Description |
|-------|------|-------------|
| `isProxy` | boolean | True if client-side proxy headers were detected |
| `proxyType` | string | One of: `transparent`, `anonymous`, `distorting`, `elite`, `none` |
| `anonymityLevel` | string | One of: `transparent`, `anonymous`, `elite`, `none` |
| `confidence` | string | Detection confidence: `high`, `medium`, or `low` |
| `detectedHeaders` | string[] | Header names that signaled a proxy (e.g. `via`, `forwarded`) |
| `explanation` | string | Plain-English summary of the result |

### `proxyChain`

| Field | Type | Description |
|-------|------|-------------|
| `originalClientIp` | string | Same as top-level `clientIp` |
| `proxyChain` | string[] | List of proxy IPs between you and FourA, if any |
| `proxyCount` | number | Number of proxies detected in the chain (0 = direct) |
| `via` | string[] | Contents of the `Via` header, if present |
| `hasPrivateIps` | boolean | True if any private/internal IPs appear in the chain |

## Proxy Types

| Type | What it means |
|------|---------------|
| `transparent` | Forwards your real IP and identifies itself as a proxy |
| `anonymous` | Hides your real IP but identifies itself as a proxy |
| `distorting` | Sends a fake client IP to the destination |
| `elite` | No proxy headers, looks like a direct connection |
| `none` | No client-side proxy detected |

## When to Use This

- Confirm your outbound traffic isn't passing through a corporate or VPN proxy you didn't expect.
- Debug why your real IP shows up in target site logs even when you thought you were anonymous.
- Verify a residential or rotating proxy is masking your origin before you send paid requests through FourA.

This endpoint inspects your connection to FourA. It does not test FourA's own proxy network. To verify which IP a FourA-routed request comes from, use the [Proxy endpoint](/docs/api/endpoints) and read the response.

## Limits

- No authentication required.
- Subject to a generous public rate limit. If you call it more than a few times per second from the same IP, expect throttling.
- The response reflects only headers and IPs. It cannot detect a perfectly transparent elite proxy that strips all proxy headers.

## Related

- [API Endpoints](/docs/api/endpoints): The authenticated request endpoints
- [Authentication](/docs/getting-started/authentication): How to authenticate the rest of the API
- [Common Issues](/docs/troubleshooting/common-issues): Debug request failures

---

#### Request Outcomes
URL: https://foura.ai/docs/api/outcomes

Every request to the FourA API is classified into exactly one outcome. The outcome is computed once at request time and recorded against your API key. Your dashboard, activity feed, and billing all read the same field.

Only `success` is billable.

## The Seven Outcomes

| Outcome | Layer | What it means |
|---------|-------|--------------|
| `success` | n/a | A valid response was delivered. Counts against your billable quota. |
| `application_error` | target | The target returned HTTP 200, but the body carried an error field. |
| `application_fail` | target | The target returned a non-2xx that your `validate` rules did not accept, or no response at all. |
| `client_error` | caller | Your request was rejected before it left FourA. Bad parameters, malformed proxy value, SSRF-guarded URL. |
| `rate_limit` | FourA | The request was refused before it ran: by one of your plan's limits (a 403 for an endpoint or parameter the plan doesn't include, a 429 for a spent allowance), or by the platform's shared RPM or concurrency allowance. |
| `service_error` | FourA | The backend returned a 5xx, or its body wasn't valid JSON. |
| `service_fail` | FourA | Network failure: timeout, connection refused, DNS error, client disconnect. |

The layer column tells you who's responsible:

- **target** outcomes are about the site you called. Your request reached FourA fine, and FourA reached the target fine. The target itself returned an error.
- **caller** outcomes mean your request never had a chance. Fix the request shape.
- **FourA** outcomes are on us. Retry, and check the [status page](https://updates.foura.ai/status) if they persist.

A target site returning `403` is `application_fail`, not `client_error`. Your call was well-formed. The site just said no.

## Success Is `validate`-Aware

Without `validate`, the API marks a request `success` only when the target returns HTTP 200.

With `validate`, success follows the rules you declared. If you tell the API that 200 and 403 are both acceptable for a given request, a 403 comes back as `success`. The body still reaches you unchanged.

```bash
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://target.example/feed",
    "validate": {
      "status": { "accept": [200, 403] }
    }
  }'
```

In this call, a 403 response counts as `success` and bills as one request. A 500 response counts as `application_fail` and is not billed.

The same logic applies to `validate.headers` and `validate.data`. Any response the engine accepts against your rules comes back as `success` regardless of HTTP status.

## Billing Implications

| Outcome | Billable | Counts toward quota |
|---------|----------|--------------------|
| `success` | Yes | Yes |
| `application_error` | No | No |
| `application_fail` | No | No |
| `client_error` | No | No |
| `rate_limit` | No | No |
| `service_error` | No | No |
| `service_fail` | No | No |

Only requests that delivered the data you asked for are billed. Failures on FourA's side, the target's side, or your own side are all free.

## Reading Outcomes in the Dashboard

Every request your API key makes shows up on the [Activity](/docs/dashboard/activity-log) feed with its outcome label. The [Metrics](/docs/dashboard/metrics) and [Overview](/docs/dashboard/overview) pages aggregate the same field for donut charts and timelines.

When you filter Activity by outcome, you can also focus on a single product (Single, Proxy, Browser) to see whether a class of failure is specific to one endpoint.

## Retry Heuristics

A first-pass retry policy keyed on outcomes:

| Outcome | Retry safe? | When |
|---------|-------------|------|
| `success` | n/a | You have the response. |
| `application_error` | Sometimes | Read the target's error body. Some are transient, most aren't. |
| `application_fail` | Sometimes | If the target is rate-limiting you, slow down. If it's blocking you, switch to the Proxy or Browser endpoint. |
| `client_error` | No | The request will fail again the same way. Fix the input. |
| `rate_limit` | Depends | Honor the wait the response gives you: `Retry-After`, `retry_after_seconds`, or `retryAfter`. On `plan_limit_browser_daily`, stop until midnight UTC; on `plan_limit_credits` or `plan_limit_bandwidth`, stop until `resets_at`; on `plan_limit_feature` or `plan_limit_premium`, change the request. |
| `service_error` | Yes | Short exponential backoff. |
| `service_fail` | Yes | Same as `service_error`. |

## Related

- [API Errors](/docs/api/errors): HTTP-level error responses
- [Rate Limits](/docs/api/rate-limits): What triggers `rate_limit`, and the two shapes it comes back in
- [Metrics](/docs/dashboard/metrics): Where you see outcomes broken down
- [Activity Log](/docs/dashboard/activity-log): Per-request outcome history

---

#### Response Headers
URL: https://foura.ai/docs/api/response-headers

Every response from the FourA API includes a small set of custom headers. They're useful for tracing, support, billing reconciliation, and post-hoc analysis.

## Headers FourA Sets

| Header | Set on | Description |
|--------|--------|-------------|
| `X-FourA-Request-Id` | Every `/api/*` response, including errors and 401s | A UUID identifying this request. Log it on your side. |
| `X-FourA-Credits` | Every `/api/*` response that reached the backend | Credits spent on this call. Returned on success and on failure (the work was done either way). |
| `X-FourA-Limit` | Every `403` or `429` raised by one of your plan's limits | Which limit refused the call: `plan_limit_` followed by `feature`, `premium`, `concurrency`, `rate`, `browser_daily`, `credits`, or `bandwidth`. |
| `Retry-After` | Plan-limit `429`s that a wait clears: concurrency, rate, credits, bandwidth | Seconds to wait, as an integer. Matches `retry_after_seconds` in the body. |
| `X-FourA-Exit-Class` | Every `/api/proxy/` call that named an `exitClass`, and every Single or Browser call served through a premium exit | `premium` or `standard`: the class of exit that delivered the body. |
| `Content-Type` | Every response | Always `application/json` for the envelope. The target's content-type comes back inside the envelope's `headers` field. |

## X-FourA-Request-Id

Each call to `POST /api/auto/`, `POST /api/single/`, `POST /api/proxy/`, or `POST /api/browser/` is tagged with a UUID. The header is set even when authentication fails, so you can correlate misconfigured calls too.

```bash
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/1.1 200 OK
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...
```

### When to use it

- **Support tickets**: include the request ID and we can find the exact call in our records.
- **Your own logs**: store it next to your application log line. If a customer complaint says "the data was wrong at 14:32", you can replay the exact request.
- **Dashboard tracing**: the same ID appears in the [Activity feed](/docs/dashboard/activity-log) for keys you manage, so you can open the matching row and inspect the captured request and response.

### Example: log on your side

```python
import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-FourA-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()
```

```javascript
async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-FourA-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}
```

## X-FourA-Credits

`X-FourA-Credits` reports the credit cost of the call you just made. It's a meter, not a bill: the header reflects what the work spent regardless of outcome. The dashboard's billing layer only counts billable outcomes against your plan (see [Request Outcomes](/docs/api/outcomes) for which outcomes are billable).

### Cost reference

| Engine | Base | With `unblocker` |
|--------|------|------------------|
| Single | 1 | 2 |
| Proxy | 5 | 10 |
| Browser | 15 | 30 (when a defense was solved) |

`/api/auto/` doesn't add a separate billable row. Its credit cost is the sum of the sub-calls it made internally (a single replay on a warm target can finish at 2; a cold solve on a hard site can spend much more). The `X-FourA-Credits` value on the auto response equals `meta.credits` in the body and tracks the full ladder cost.

### Why both a header and a body field?

The header is convenient: you can read it before parsing the body, log it next to your request line, or sum it across many calls without JSON parsing. The body's `meta.credits` (Auto) or per-engine metadata (Single, Proxy, Browser dashboards) holds the same number, but readable inside the response envelope.

## X-FourA-Limit

`X-FourA-Limit` appears only when one of your plan's limits refused the call. The platform's shared rate limits never set it, so the header is the fastest way to tell "my plan stopped this" from "FourA is busy" without parsing the body.

```
HTTP/1.1 429 Too Many Requests
X-FourA-Limit: plan_limit_concurrency
Retry-After: 1
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
Content-Type: application/json
```

Two of the seven values come with a 403 rather than a 429: `plan_limit_feature` (the endpoint or the `exitCountries` parameter isn't in your plan) and `plan_limit_premium` (`exitClass: premium` isn't in your plan). Neither sets `Retry-After`, because waiting doesn't change the answer.

```python
STOP_ON = {
    "plan_limit_feature", "plan_limit_premium",
    "plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth",
}

resp = requests.post(url, headers=headers, json=payload)

limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
    stop_the_run(limit)                # hours or days away, not seconds
elif limit:
    time.sleep(int(resp.headers.get("Retry-After", 1)))
```

The seven values and the body fields that come with each are in [Rate Limits](/docs/api/rate-limits).

## X-FourA-Exit-Class

`X-FourA-Exit-Class` names the class of exit that delivered the body: `premium` when a premium exit did, `standard` when the standard pool did. It appears on a `POST /api/proxy/` response whenever the request named an `exitClass`, where the body carries the same value, and on a Single or Browser response whenever the `proxy` you pinned was a premium exit, where the body has no field for it.

```
HTTP/1.1 200 OK
X-FourA-Exit-Class: premium
X-FourA-Credits: 2
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

Bytes served through a premium exit count toward your premium traffic as well as your total bandwidth. Read the header per request if you reconcile premium traffic yourself; the [Usage & Limits](/docs/dashboard/quota) page shows the same figures for the billing period. What `exitClass` does and when a premium exit is used: [exitClass](/docs/api/endpoints#exitclass).

## Cache Behavior

The API does not set `Cache-Control` or `ETag` on responses. Every call hits the backend. If you need caching, add it on your side.

## Target Response Headers

The headers the target site returned are not on the FourA API response. They come back inside the JSON envelope as the `headers` field. For the Single and Proxy endpoints, this is an array of per-hop header objects (one entry per redirect step). For the Browser endpoint, it's a flat object of the final response headers.

```json
{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}
```

If you need a specific target header, read it from the envelope's `headers` field, not from the HTTP response of the API call itself.

## Related

- [API Endpoints](/docs/api/endpoints): Request and response envelope shapes
- [API Errors](/docs/api/errors): How error responses are structured
- [Request Outcomes](/docs/api/outcomes): Which outcomes are billable
- [Activity Log](/docs/dashboard/activity-log): Per-request history keyed by request ID
- [Rate Limits](/docs/api/rate-limits): What each `X-FourA-Limit` value means

---

#### Anti-Bot Defenses
URL: https://foura.ai/docs/api/anti-bot-defenses

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 [Handling Anti-Bot Protection](/docs/guides/anti-bot-protection).

## 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) | A bot check was recognised during the page load |
| `POST /api/auto/` | `meta.solved` (boolean) | Always. `true` when a check was cleared somewhere on the ladder. |

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

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. Today the one value is `refusal-cookies`. 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 an unsolved challenge 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.

## `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 15 or 30 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 can recognise but not yet get past. 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 |
| `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` |

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 captcha field 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](/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 | 5 (10 with `unblocker`) | No change |
| Browser | 15 | 30 |

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

## 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

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

---

#### Proxy Port
URL: https://foura.ai/docs/api/proxy-port

Send your own traffic through FourA's exits from any client that accepts a proxy URL: a browser, a download tool, a scraper you already run. The proxy port opens a tunnel to the target you name and copies bytes both ways, so it carries what the JSON API doesn't: streams, large downloads, and whole browser sessions.

**Beta.** The proxy port is in beta. Traffic through it isn't billed yet, it isn't covered by monitoring or an uptime commitment, and option names can still change. Tell us what breaks.

## Connecting

| Setting | Value |
|---------|-------|
| Host | `proxy.foura.ai` |
| Port | `34004` |
| Protocol | HTTP CONNECT with Basic authentication |
| Target ports | `443` and `80` |

Credentials come from the dashboard. Create a proxy user under **Proxy** in the sidebar and you get a generated username and password. They're separate from your API key on purpose: a proxy handshake travels in the clear on every connection, and a proxy user can be rotated without touching your API integration. See [Proxy Users](/docs/dashboard/proxy).

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 https://example.com
```

```python
import requests

proxy = "http://USERNAME:PASSWORD@proxy.foura.ai:34004"
r = requests.get("https://example.com", proxies={"https": proxy, "http": proxy})
print(r.status_code)
```

The port speaks CONNECT only. An `https://` target is tunnelled by every client. A plain `http://` target works when your client tunnels it too (curl: `--proxytunnel`); a client that forwards the plain request to the proxy instead gets `405 Method Not Allowed`.

## Options Ride in the Username

Everything after the credential is a list of `-key-value` pairs, in any order:

```
USERNAME-network-residential-country-de-session-a1
```

Values are lowercase words. A dash inside a value starts a new option, so `-city-new-york` reads as two options and is refused. An unknown key is refused too, never dropped: a misspelt `-contry-de` comes back as a 400 that names the supported keys, rather than being served from the wrong country.

| Option | Values | What it does |
|--------|--------|--------------|
| `network` | `shared` (default, alias `pool`), `residential` | Which network the address comes from. Shared is FourA's own exits, included in your plan. Residential is home addresses, drawn from the premium traffic your plan includes plus any you bought. |
| `fallback` | `residential`, `off` | Shared network only. Take a residential exit when the shared network can't carry the request. Off unless asked for, and it only fires when your plan includes premium traffic and allowance remains. |
| `country` | ISO 3166-1 alpha-2, repeatable | The exit country the target sees. Repeat it for a multi-country scope: `-country-de-country-fr`. |
| `session` | 1 to 32 letters, digits, or underscores | Connections sharing a name share an address (sticky). Omit it for a new address per connection (rotating). |
| `state` | a word | Region. Residential only. |
| `city` | a word | City. Residential only. |
| `asn` | a number | Network, by AS number. Residential only. |
| `os` | `windows`, `android`, `ios`, `mac` | The kind of device the address belongs to. Residential only. |
| `lifetime` | `3` to `1440` | Minutes a sticky residential address is held. Residential only. |

Every option except `network`, `fallback`, and `session` accepts `any`, which clears a value saved on the proxy user for this one connection.

Three combinations are refused with a 400 rather than partly honoured:

- `state`, `city`, `asn`, `os`, or `lifetime` on the shared network. The shared network is chosen by country and nothing finer; add `-network-residential` to target a city.
- `-fallback-residential` together with `-network-residential`. A fallback has nothing to do on the network it falls back to.
- Finer targeting with a fallback armed. A fallback may or may not fire, so a city it could only sometimes honour is refused.

### Sessions

On the shared network, a named session keeps the same exit for as long as you keep using it, on a sliding ten-minute window. If that exit stops working, the session moves to another one rather than failing. A browser driven through the port should always carry a session name: a page load opens dozens of connections, and without a session each one leaves from a different address.

On the residential network, a named session holds its address for `lifetime` minutes, or the network's default when you don't set one.

### Saved defaults

Targeting saved on a proxy user in the dashboard applies to every connection made with it, so the username can stay short. Anything you put in the username wins for that one connection, and `any` takes a saved value back. A saved residential default spends only when your plan allows it; otherwise the connection is served from the shared network.

### CONNECT headers

A client that can add headers to the CONNECT request may send the same options as headers. A header wins over the same option in the username.

| Header | Same as |
|--------|---------|
| `X-Foura-Network` | `-network-` |
| `X-Foura-Fallback` | `-fallback-` (`residential` or `off`) |
| `X-Foura-Country` | `-country-`, comma-separated for several |
| `X-Foura-Session` | `-session-` |
| `X-Foura-State` | `-state-` |
| `X-Foura-City` | `-city-` |
| `X-Foura-Asn` | `-asn-` |
| `X-Foura-Lifetime` | `-lifetime-` |

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 \
  --proxy-header "X-Foura-Country: de" \
  https://example.com
```

## Responses

A tunnel that opens answers `200 Connection established`. Every refusal carries an `X-Foura-Error` header with a one-line reason, so read that header before anything else.

| Status | When |
|--------|------|
| 400 Bad Request | A malformed request, or an option FourA can't honour. `X-Foura-Error` spells out the option and the supported values. |
| 403 Forbidden | The target port isn't served, or the target isn't a public internet host. |
| 405 Method Not Allowed | A plain request instead of CONNECT. |
| 407 Proxy Authentication Required | Missing or wrong credentials. The answer never says which half was wrong. |
| 408 Request Timeout | The client connected and sent nothing for 15 seconds. |
| 429 Too Many Requests | The proxy user already has 200 tunnels open, or the port is at its capacity or opening rate. |
| 502 Bad Gateway | No working exit was found for that target within the selection budget, or FourA's own resolver couldn't look the host up. The two are different messages in `X-Foura-Error`. |
| 503 Service Unavailable | The proxy port is switched off. |

## Limits

- Up to 200 tunnels open at once per proxy user.
- Finding an exit takes up to 45 seconds before the port gives up with a 502. A session that already has an exit usually connects in well under a second.
- A tunnel with no bytes in either direction is closed after two idle minutes.
- A proxy user you disable or delete in the dashboard stops authenticating within a minute.

## Metering

Bytes through the port count toward the bandwidth on your [Usage & Limits](/docs/dashboard/quota) page, and bytes through a residential exit count toward your premium traffic as well. A connection that names `-network-residential` after the premium allowance is spent is served anyway; a fallback or a saved residential default isn't taken in that state, and the shared network serves the connection instead.

## Related

- [Proxy Users](/docs/dashboard/proxy): Create proxy users and build a connection string in the dashboard
- [Proxy Request](/docs/api/endpoints#proxy-request): The JSON API alternative, with retries and validation built in
- [Reuse a Proxy Across Requests](/docs/how-to/reuse-a-proxy): Keeping one exit on the JSON API
- [Usage & Limits](/docs/dashboard/quota): Bandwidth and premium traffic against your plan

---

### Dashboard

#### Dashboard Overview
URL: https://foura.ai/docs/dashboard/overview

The FourA Dashboard is where you manage API keys, run test requests, monitor performance, handle billing, and configure your account. This page walks through the main Overview screen and the sidebar sections.

## Accessing the Dashboard

Sign in at [foura.ai/dashboard](https://foura.ai/dashboard). You need a FourA account: [sign up here](https://foura.ai) if you don't have one.

## Overview Page

The landing page after sign-in shows your headline numbers for the period you pick.

### Summary Cards

Five panels across the top:

| Panel | What it shows |
|------|---------------|
| Concurrency | Requests running at the same time right now, plus the average and max for the period |
| Requests | Total calls, then Single, Proxy, and Browser, each with its share of the total underneath |
| Credits | Billed credits as the value, spent credits underneath, for the total and for each product |
| Bytes | Data transferred: In is what you sent, Out is what came back, and Premium is the part of that traffic served through a premium exit. Premium sits inside the two totals and is never added to them. |
| Response Time | Average, min, and max across the period |

**Billed and spent are different numbers.** Only a successful request is billed, so billed is what you pay for. Spent is every outcome, because a failed request still consumes a proxy or a browser. Reading one under the other's name is how the same account ends up looking like two different accounts on two pages. See [Request Outcomes](/docs/api/outcomes) for which outcomes bill.

The three products don't always add up to the total. A small number of calls carry neither, and they're counted in the total and in no product.

### Timeline Charts

Below the panels, six timeline charts plot request volume, credit spend, outcome breakdown, response time, bandwidth, and concurrency. Every chart has a toggle in its header that swaps the plot for the underlying table.

### Period and Detail

**Period** is how far back you're looking. Eight pills plus Custom:

| Pill | Window |
|------|--------|
| 30M | Last 30 minutes |
| 3H | Last 3 hours |
| 12H | Last 12 hours |
| 24H | Last 24 hours |
| 7D | Last 7 days |
| 30D | Last 30 days |
| 90D | Last 90 days |
| 1Y | Last 12 months |

**Custom** opens a dialog with four presets, This month, Last month, Last 6 months, and All time, plus a From and To date pair. A date range runs to the end of the day you picked, never past this moment.

**Detail** is how wide each bar is: per minute, every 5 minutes, every 30 minutes, hourly, every 6 hours, daily, weekly, or monthly. It defaults to **Auto**, which picks the coarsest step that still puts at least fifteen bars on the chart, so a year reads as a shape instead of 365 hairs. The Auto option names the step it chose.

Detail steps that reach further back than FourA keeps that resolution are greyed out rather than hidden:

| Resolution | How far back it goes |
|-----------|---------------------|
| Per-request | 7 days |
| 5-minute | 30 days |
| Hourly | 12 months |
| Daily | The whole history |

Pick a period older than a level allows and the finer options grey out. Auto never picks one of them, so a chart is never empty because the data was aggregated away.

### Filters

Filters stack and combine, and Period and Detail sit alongside them.

| Filter | What it does |
|--------|--------------|
| Product | Scope to one endpoint: Single, Proxy, or Browser. Auto sub-calls appear under the product that ran them, since Auto isn't a separate billable row. |
| Outcome | Isolate one category: Success, Client Error, Service Error, Service Fail, Rate Limited, App Error, or App Fail |
| Owner | Everything, Personal, or one of your organizations. Appears only when you belong to at least one. |
| Key | Restrict to a single API key |

The Concurrency panel and chart don't take the Product or Outcome filter. Both dim while either is on, and the chart says so on its header.

### The Owner Filter

The **Owner** dropdown answers "whose traffic am I looking at". It offers **Everything**, **Personal**, and one entry per organization you belong to, and the same control on Metrics, Activity, and API Keys follows your choice, so the four pages never disagree.

Usage & Limits and Billing deliberately don't take it. They answer "what bills to me", which for you is your personal keys plus the keys of organizations you own. See [Organizations](/docs/dashboard/teams-and-orgs).

## Sidebar Sections

The sidebar links to ten sections, grouped under Dashboard, Access, and Account.

### Overview

The page above. Always the starting point after sign-in.

### Playground

Test live requests against your real API key without writing any code. Pick Auto, Single, Proxy, or Browser, set a URL, tweak flags and timeouts, and hit Send. Save common configurations as presets, replay any of your last 20 runs from History.

Usage counts against the key's quota, the same way a production call would. See the [Playground guide](/docs/dashboard/playground).

### Metrics

Outcome distribution donut and a usage table grouped by API key, client IP, or domain.

### Activity

A live feed of your most recent API requests. Each entry shows the method, target domain, status, outcome, duration, transfer size, and credits. Use it to debug individual requests or check that a new integration is working.

### API Keys

Create, view, and manage the keys your applications use to call the API. Keys use the `pk_live_` prefix. See [Managing API Keys](/docs/dashboard/api-keys).

### Proxy

Send your own traffic through FourA's exits from any client that accepts a proxy URL. Create a proxy user, pick a network and a country, and copy the connection string. The section carries a **Beta** badge: traffic through the proxy port isn't billed yet, it isn't covered by monitoring or an uptime commitment, and option names can still change. See [Proxy Users](/docs/dashboard/proxy) and the [Proxy Port](/docs/api/proxy-port) reference.

### Organizations

Share keys with colleagues under one owner. Add people by email, set their role, and hand the organization over when it needs to change hands. Usage on an organization key counts against the organization owner's plan. See [Organizations](/docs/dashboard/teams-and-orgs).

### Usage & Limits

Your plan, what you've used this billing period, and every limit you're measured against, with a per-key and per-product breakdown. See [Usage & Limits](/docs/dashboard/quota).

### Billing

Manage your subscription, buy more credits or traffic, manage payment methods and invoices, and see this period's credits, bandwidth, and premium traffic against your plan.

### Settings

Display name and company, password, active sessions, and connected sign-in providers. Email changes aren't available in the dashboard: contact support.

## Tips

- Use the **Playground** before writing code. If you don't know which engine a new site needs, start with Auto and let it pick.
- Compare billed against spent on the Credits card. A product where the two are far apart is failing often, and the [attempt report](/docs/troubleshooting/proxy-attempt-report) says why.
- Keep your API keys secure. Disable any key immediately if you suspect it's been exposed.

## Next Steps

- [Authentication](/docs/getting-started/authentication): API key creation and management details
- [Quick Start](/docs/getting-started/quick-start): Make your first request from the CLI
- [Playground](/docs/dashboard/playground): Run live requests from the dashboard
- [Usage & Limits](/docs/dashboard/quota): Track credits against your plan
- [API Endpoints](/docs/api/endpoints): Use the API directly

---

#### Creating a Task
URL: https://foura.ai/docs/dashboard/creating-a-task

This guide walks you through creating an API key and sending your first request using the FourA Dashboard.

## Step 1: Open the Dashboard

Navigate to the [Dashboard](https://foura.ai/dashboard) and sign in with your FourA account.

## Step 2: Create an API Key

Go to the **API Keys** page and click **Create Key**.

Give the key a descriptive name (e.g., "production-scraper" or "dev-testing"). The confirmation dialog shows the plain key with a copy button.

If you miss it, click the eye icon on the key's row later to reveal it again. Legacy keys created before reveal shipped can't be brought back; regenerate them once to switch over. Full flow: [Managing API Keys](/docs/dashboard/api-keys).

Your key looks like this: `pk_live_a1b2c3d4e5f6...`

## Step 3: Choose an Endpoint

FourA has four endpoints for different scenarios:

### Auto (`POST /api/auto/`)

The smart default. Pass a URL plus a `validate` rule and FourA picks the cheapest path that works: direct request, rotating proxy, or full browser. Best when you're targeting a new site and don't yet know what it needs.

### Single (`POST /api/single/`)

Sends a fast HTTP request. Best for static HTML pages and API endpoints. Response time: typically under 2 seconds.

### Browser (`POST /api/browser/`)

Runs a Chrome browser instance to render JavaScript. Best for SPAs, lazy-loaded content, and pages that require JS execution. Response time: 2 to 10 seconds.

### Proxy (`POST /api/proxy/`)

Routes the request through rotating proxies with automatic retry. Best for sites with bot detection or geo-restricted content.

## Step 4: Send Your First Request

Open a terminal and run:

```bash
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"}'
```

## Step 5: Read the Response

```json
{
  "status": 200,
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html; charset=UTF-8",
      "content-length": "1256"
    }
  ],
  "data": "<html>...</html>",
  "total_time": 0.45
}
```

The `headers` field is an array of objects, one per redirect hop. Each entry has a `result` with the status line plus every response header the target returned.

Key fields:
- **status**: HTTP status code from the target site
- **data**: the response body (HTML, JSON, or raw text)
- **total_time**: request duration in seconds

## Step 6: Try a Browser Request

If the target page uses JavaScript to render content, use the browser endpoint instead:

```bash
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/products", "timeout_ms": 15000}'
```

The browser response uses `body` instead of `data`:

```json
{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<html>...</html>"
}
```

## Common Issues

| Problem | Solution |
|---------|----------|
| Not sure which engine to use | Start with the auto endpoint. It picks the right path and remembers what worked. |
| Empty content | Switch from single to browser endpoint: the page likely needs JS rendering |
| Captcha in response | Switch to the proxy endpoint for automatic IP rotation |
| Timeout | Increase `timeout_ms` or verify the URL is correct |
| Lost your key | Click the eye icon on the key's row in **API Keys** to reveal it, or regenerate if the key is legacy |

## Next Steps

- [Dashboard Overview](/docs/dashboard/overview): Full dashboard walkthrough
- [Playground](/docs/dashboard/playground): Test requests in the dashboard before writing code
- [Smart Fetch (Auto)](/docs/guides/smart-fetch): Deep dive on the auto endpoint
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): Detailed comparison
- [Common Issues](/docs/troubleshooting/common-issues): Solve problems quickly

---

#### Managing API Keys
URL: https://foura.ai/docs/dashboard/api-keys

The API Keys page lets you create, view, and manage the keys your applications use to call the FourA API.

## Viewing Your Keys

The page shows every key you have access to: your personal keys, and every key owned by an organization you belong to. Membership is what grants access, so a plain member sees the organization's keys too.

| Column | What it shows |
|--------|---------------|
| Name | Display name and, if you set one, the description |
| Owner | `Personal`, or the organization's name |
| Key Prefix | Masked prefix (`pk_live_••••••••`) with a Reveal button, or a lock icon on a legacy key |
| Status | Active or Inactive |
| Created | When the key was created |
| Last Used | When the key last made a request |

Search by name or description, filter to Active or Inactive, and sort by any header. Sort direction cycles descending, ascending, then off.

### The Owner Filter

If you belong to at least one organization, an **Owner** dropdown appears next to the search box: **Everything**, **Personal**, or one entry per organization. It narrows the list to keys with that owner, and the same control on Overview, Metrics, and Activity follows your choice, so the four pages always agree about whose traffic you're looking at.

## Creating a Key

Click **Create Key** and fill in:

| Field | Required | Description |
|-------|----------|-------------|
| Name | Yes | A descriptive label, for example "production-scraper" or "staging-test" |
| Description | No | Notes about what this key is used for |
| Owner | Yes if you're in an organization | Personal, or any organization you belong to. The picker only appears when you have at least one. |

Any member of an organization can create a key it owns, whatever their role. That's the point of the setting: usage on an organization key bills the organization's owner, so a developer doesn't need a personal key that quietly bills them instead of the company.

The full key is shown once right after creation in a copy-ready dialog. You can bring it back later with **Reveal**. Keys use the `pk_live_` prefix and look like `pk_live_a1b2c3d4e5f6...`. You'll get an email confirming the key was created.

## Revealing a Key

Click the eye icon next to a key's masked prefix to see its full secret again. The dashboard asks you to confirm, then opens a dialog with the plain key, a copy button, and a short countdown. After the countdown, the dialog wipes the secret from the page.

Every reveal is recorded in the audit log, because it exposes a live credential.

Anyone the key is shared with can reveal it: its personal owner, or any member of the organization that owns it.

### Legacy Keys

Keys created before the reveal feature shipped show a lock icon instead of the eye and can't be revealed. Only their hash was stored, so the original secret is unrecoverable. To switch a legacy key over, open the actions menu and choose **Regenerate**. The new secret is revealable from then on.

## What Each Role May Do

On a personal key you can do everything. On an organization key, three levels apply:

| Action | Member | Admin | Owner |
|--------|--------|-------|-------|
| Use the key and reveal it | Yes | Yes | Yes |
| Rename it, edit the description | Yes | Yes | Yes |
| Enable or disable it | No | Yes | Yes |
| Regenerate the secret | No | Yes | Yes |
| Delete it | No | Yes | Yes |
| Edit the IP allowlist or expiry | No | Yes | Yes |
| Move it out of the organization | No | No | Yes |

Buttons you can't use are disabled with a note saying why, and the API refuses the same actions, so an integration can't route around the interface.

The split follows what each action costs the people sharing the key. Renaming is harmless. Regenerating or disabling stops every colleague's integration the instant it happens. Moving a key out takes it away from the company and puts its usage on the taker's own plan, so that one is the owner's alone.

## Editing a Key

Click **Edit** to update the display name and description. Owners and admins also get the IP allowlist and expiry here. Ownership isn't changed on this dialog: use **Transfer**.

## Activating and Deactivating

Use **Disable** or **Enable** on the row. Deactivating a key blocks every API request that uses it, and you can reactivate it at any time. The change takes effect within seconds.

## Regenerating a Key

If you suspect a key has been exposed, open the actions menu and choose **Regenerate**. This creates a new secret for the same key ID. The old secret stops working immediately. Name, owner, and every other setting stay the same.

The new secret stays revealable after the dialog closes, so you don't have to copy it perfectly on the first try.

## Transferring a Key

**Transfer** in the actions menu moves a key between personal and organization ownership without regenerating the secret. The key ID, its metrics, and its activity history are preserved. Only the owner changes, and with it who the usage bills to.

| Move | Who can do it |
|------|---------------|
| Personal key into an organization | Anyone who belongs to that organization |
| Organization key out, to yourself | The organization's owner |
| Between two organizations | The owner of the organization the key is leaving |

A key that moves into an organization joins its default "Everyone" team, which is what makes it visible to the members. A key that moves out leaves every team it was in.

## Deleting a Key

Open the actions menu and choose **Delete**. Deleting a key you've used before soft-deletes it: the key stops authenticating, and its Activity and Metrics history stay intact. Keys that have never been used are removed outright.

You'll get an email when a key is deleted.

## Organization Keys and Billing

Usage on an organization-owned key counts against the **organization owner's** plan, whoever fired the request. The owner's [Usage & Limits](/docs/dashboard/quota) page counts those keys alongside their personal ones and splits the two.

## Related

- [Authentication](/docs/getting-started/authentication): How API keys work with the API
- [Organizations](/docs/dashboard/teams-and-orgs): Roles, members, and shared access
- [Usage & Limits](/docs/dashboard/quota): Which keys count against your plan
- [Dashboard Overview](/docs/dashboard/overview): All dashboard sections

---

#### Metrics
URL: https://foura.ai/docs/dashboard/metrics

The Metrics page (sidebar > Metrics) gives you a deeper analytical view of your API usage. It shows your overall outcome distribution and breaks down traffic by API key, client IP, or target domain.

For summary cards and timeline charts (Concurrency, Requests, Credits, Bytes, Response Time), use the [Dashboard Overview](/docs/dashboard/overview) page.

## Filters

Four controls sit above the page: Owner, Key, Period, and Detail. They're the same controls as on Overview and they share their state, so switching between the two pages never changes what you're looking at.

### Owner Filter

**Everything**, **Personal**, or one of your organizations. It only appears once you belong to at least one. Picking an owner also rebuilds the Key dropdown, so a key from the previous owner can't survive the switch and silently return nothing.

### Key Filter

Scope the page to a single key. Only keys you have access to appear: your personal keys and the keys of organizations you belong to.

### Period

Eight pills, 30M, 3H, 12H, 24H, 7D, 30D, 90D, and 1Y, plus **Custom** for a calendar month, the last 6 months, all time, or an exact pair of dates.

### Detail

How wide each bar is, from per minute up to monthly. It defaults to **Auto**, which picks the coarsest step that still leaves the chart readable. Steps reaching further back than FourA keeps that resolution grey out. Full explanation in [Dashboard Overview](/docs/dashboard/overview).

## Outcome Distribution

A donut chart at the top shows the success and error breakdown for the selected period. Hover any slice for the exact request count and percentage. Use it to check whether a drop in success rate lines up with one outcome category.

## Outcome Types

Every API request is classified into exactly one outcome. Only `success` is billed.

| Outcome | Layer | Meaning |
|---------|-------|---------|
| `success` | n/a | The request delivered a valid response. With no `validate` rules, that means HTTP 200. With `validate` rules, any response your rules accepted, whatever the status. |
| `application_error` | target | The target returned HTTP 200, but the body carried an error field. |
| `application_fail` | target | The target returned a non-2xx your `validate` rules didn't accept, or no response at all. |
| `client_error` | caller | Your request was rejected before it left FourA: bad parameters, a malformed proxy value, or a URL that resolves to a private or reserved IP. |
| `rate_limit` | FourA | The request was rejected by your RPM or concurrency limit. See [Rate Limits](/docs/api/rate-limits). |
| `service_error` | FourA | The backend returned a 5xx, or replied with a body we couldn't parse. |
| `service_fail` | FourA | A network failure: timeout, connection refused, DNS error, client disconnect. |

The layer column tells you who's responsible. `target` means the site you called, `caller` means your request was bad, `FourA` means we couldn't process it.

If you use `validate.status.accept` to allow specific non-200 codes (for example `[200, 403]`), those come back as `success` instead of `application_fail`. The classification follows the engine's verdict on your rules, not the raw HTTP code.

For the full taxonomy and how it maps to billing, see [Request Outcomes](/docs/api/outcomes).

## Usage Table

Below the donut, a usage table breaks down your traffic with three view tabs:

| Tab | Groups data by |
|-----|----------------|
| API Key | Each key you have access to |
| Client IP | Source addresses making the requests |
| Domain | Target domains in your requests |

Scope chips on the right change the columns:

| Scope | What it shows |
|-------|---------------|
| Bandwidth | Request count, bytes in, bytes out, and the premium share of those bytes (traffic served through a premium exit, inside the totals rather than added to them) |
| Response Time | Request count, min, average, max latency |
| Concurrency | Request count plus concurrent request counts (API Key view only) |
| Outcomes | Request count plus a per-outcome breakdown |
| Budget | Request count and credits spent, by product |

The Budget scope reads the credits metric the API reports on every request (see [Response Headers](/docs/api/response-headers)). Those sums are the raw metered spend. Billing counts only the `success` outcome against your plan, and the Overview Credits card shows both side by side.

Click a column header to sort. Sort state persists per table across page loads. Ctrl or Cmd click a header to reset.

## Related

- [Dashboard Overview](/docs/dashboard/overview): Summary cards, timeline charts, Period and Detail
- [Request Outcomes](/docs/api/outcomes): The seven outcome values explained in detail
- [Response Headers](/docs/api/response-headers): Where credits come from
- [Organizations](/docs/dashboard/teams-and-orgs): What the Owner filter covers
- [API Errors](/docs/api/errors): How errors come back over the wire

---

#### Activity Log
URL: https://foura.ai/docs/dashboard/activity-log

The Activity Log shows your most recent API requests in real time. Use it to debug individual requests, check response codes, and verify that your integration is working.

## What You'll See

The log displays requests made within the last hour, with the most recent at the top. Nine columns carry the whole row:

| Column | What it shows |
|-------|-------------|
| Time | When the request was made |
| Key | Which API key was used |
| Request | The call itself: a colored product dot (single, proxy, or browser), the HTTP method, and the target domain. Sorts by domain. |
| Status | Two values in one cell, separated by a slash: the HTTP status of your call to FourA, then the status the target returned. A dash means the target never answered. |
| Outcome | Request classification (Success, Client Error, Rate Limited, and so on) |
| Duration | Total response time in milliseconds |
| Bytes | Transfer both ways in one cell: down arrow for the request payload, up arrow for the response. A row served through a premium exit carries a **premium** mark on this cell; those bytes count toward your premium traffic. |
| Credits | Credits spent on the call (see [Response Headers](/docs/api/response-headers)) |
| Client IP | The address that made the request |

Click any column header to sort the table by that column; direction cycles descending, ascending, then off. Ctrl or Cmd click resets to the default (newest first).

## Filtering

Four controls narrow the log.

### By Owner

If you belong to at least one organization, an **Owner** dropdown appears first: **Everything**, **Personal**, or one of your organizations. Changing it rebuilds the key dropdown next to it, so a key belonging to the previous owner can't survive the switch and silently return nothing. The same control on Overview, Metrics, and API Keys follows your choice. See [Organizations](/docs/dashboard/teams-and-orgs).

### By API Key

Use the API key dropdown to show requests from one key. Only keys you have access to appear: your personal keys and the keys of organizations you belong to.

### By Product

Filter to one endpoint with the **single / proxy / browser** selector. Useful when you want to debug browser-only failures separately from single requests.

### By Limit

The activity log defaults to 50 entries. Use the limit selector to change how many entries are shown:

| Limit | Notes |
|-------|-------|
| 10 | Quick scan |
| 50 | Default |
| 100 | Extended view |
| 200 | Maximum |

All entries are from the last hour. For historical data, use the [Metrics](/docs/dashboard/metrics) section, which aggregates data over days and weeks.

## Opening a Request

Click any row to open a detail panel with the full request and response payload preview. The panel opens on a meta grid built from the row itself, so it stays useful even after the stored payload has aged out: timestamp, key, HTTP status, app status, outcome, duration, credits, proxy, and the request's `X-FourA-Request-Id`.

Below the grid, one pane shows at a time, selected by tab:

| Tab | What it shows |
|-----|---------------|
| Request | Pretty-printed JSON of the exact body sent |
| Response headers | The headers the target returned, with a count on the tab |
| Response body | The stored body preview, with truncated and binary badges where they apply |
| Other fields | Anything else the engine returned beyond status, timings, proxy, and headers. Hidden when there's nothing extra. |

A **Copy** button copies whichever pane is open. Payloads are kept for 24 hours, capped at the last 200 per API key. Rows older than that show the row only, without a payload.

### Body Pane Messages

The body pane uses different placeholder text depending on what happened:

| Message | What it means |
|---------|---------------|
| `(no body — the request failed: <error>)` | The request errored before the target returned a body |
| `(no body captured for this request)` | Payload aged out or wasn't stored |
| `(empty body — the server returned 0 bytes)` | The target returned a real empty response |

## Open in Playground

The detail dialog has an **Open in Playground** button. Click it to load both the archived request and the archived response into the [Playground](/docs/dashboard/playground) form. From there you can tweak parameters and replay against the live API, or just inspect what came back without re-running the request.

The button is disabled for non-replayable payloads (oversized request stubs and non-API routes), with a hint explaining why.

## Using the Request ID

Every API response carries an `X-Foura-Request-Id` header. Log it on your side, and you can paste it into a support ticket to point at the exact request in the Activity Log. The ID is the same one used in this dialog and matches the `X-Foura-Request-Id` returned by the API. See [Response Headers](/docs/api/response-headers) for details.

## Related

- [Metrics and Analytics](/docs/dashboard/metrics): Aggregated performance data over longer periods
- [Playground](/docs/dashboard/playground): Replay requests from Activity
- [Response Headers](/docs/api/response-headers): Where the request ID and credits come from
- [API Endpoints](/docs/api/endpoints): Request and response shapes
- [Organizations](/docs/dashboard/teams-and-orgs): What the Owner filter covers
- [Troubleshooting](/docs/troubleshooting/common-issues): Common problems and solutions

---

#### Usage & Limits
URL: https://foura.ai/docs/dashboard/quota

The Usage & Limits page in the dashboard shows your plan, what you've used this billing period, and every limit you're measured against.

## Where to Find It

Sign in to the [dashboard](https://foura.ai/dashboard) and open **Usage & Limits** in the sidebar.

## Overview Tab

- **Billing period context**: the exact start and end dates of the window you're in. Paid plans reset on your billing date each month. Annual plans get monthly cycles anchored to activation. The Free plan anchors to your signup date.
- **Credits this period**: five stats side by side. Billed, Spent, Included, Remaining, and Overage. Only successful requests are billed and count against your plan. Spent is the total resource use including failed requests, which we never charge for. A usage bar under the stats colors amber at 80% and red at or over the included allowance.
- **Per-product breakdown**: cards for Single, Proxy, and Browser show the credits and requests each product used this period, plus a last-used timestamp.

## API Keys Tab

A sortable table of every key that answers to your plan, with billed credits, spent credits, requests, share of usage, and last used. Keys of organizations you own count against your plan too. Deleting a key never deletes its usage history.

This page ignores the dashboard's **Owner** filter on purpose. It answers "what bills to me", which is your personal keys plus the keys of organizations you own. A member of somebody else's organization never sees the owner's quota. See [Organizations](/docs/dashboard/teams-and-orgs).

## Limits & Features Tab

- **Plan limits**: one row per limit with your current value, what's included, and the status.

| Row | What it counts |
|-----|----------------|
| API keys | Active keys you answer for, split into personal and organization |
| Team members | The largest organization you own, its owner included. An organization you only belong to counts against its owner, not you. |
| Organizations you own | How many you own, and whether your plan covers having one at all |
| Credits (this period) | Billed credits against what's available: what the plan includes plus any credits you bought, shown apart (`75,000 (50,000 incl + 25,000 bought)`) |
| Bandwidth | Data transferred against your allowance, when your plan carries a cap. Bought bandwidth counts the same as included bandwidth. |
| Of which premium | The share of that bandwidth served through a premium exit, against the premium traffic your plan includes plus any you bought. Running out reads **spent**, never over: requests keep working on the standard pool and the response says `exitClass: standard`. A plan with none included reads **top-up only**. |
| Per product | Requests per minute, concurrency, and browser requests per day for Single, Proxy, and Browser, each with its live counter next to the plan's number. A product your plan excludes reads **Not in plan**. |
- **Plan features**: the capabilities included in your plan, such as geo targeting (`exitCountries`) and premium exits (`exitClass`). Features not in your plan show as excluded so you can see what an upgrade would unlock.

The numbers in this tab are the ones the API holds you to. A refusal from any of them arrives with an `X-FourA-Limit` header naming the row: see [Rate Limits](/docs/api/rate-limits).

## Freshness

Numbers on this page come from the billing pipeline and refresh every few seconds. If a request finished a moment ago, give the page one refresh to catch up. Live counters for concurrency, per-minute rate, and browser-per-day sit next to your caps and update in near real time.

## Related

- [Billing & Subscriptions](/docs/dashboard/billing): Manage your plan, buy more credits or traffic, payment methods, and invoices
- [Metrics](/docs/dashboard/metrics): Timelines, outcome breakdown, and per-key charts
- [Activity Log](/docs/dashboard/activity-log): The last 200 requests per key with payloads
- [Organizations](/docs/dashboard/teams-and-orgs): Members, roles, and who the usage bills to
- [Rate Limits](/docs/api/rate-limits): What triggers rate-limit responses

---

#### Billing & Subscriptions
URL: https://foura.ai/docs/dashboard/billing

The Billing section is where you manage your subscription, buy more of what your plan meters, and keep payment methods, invoices, and standing invoice details in order. Open it from the **Billing** link in the dashboard sidebar.

The page has four tabs: Plan & Usage, Billing Details, Payment Methods, and Invoices.

## Plan & Usage

### Current plan

The first card names the plan you're on and its status (Active, Trialing, Past due, Cancelled, and so on), with the renewal date underneath. A plan an operator placed with a start date in the future reads **Starts** with that date instead of **Renews**.

The buttons on the card depend on where you are:

| Button | When it appears |
|--------|-----------------|
| Change plan | You're on an active plan. Opens the plan picker, with proration. |
| Cancel | You're on an active plan. |
| Resume | You cancelled, and the period hasn't ended yet. |
| Confirm *plan* | FourA placed you on a paid plan you haven't paid for yet. Opens checkout so you pick how to pay. |
| Start *plan* | FourA offered you a plan that carries no charge, such as a trial. Starts it without a card. |
| Your custom plan: *plan* | A custom plan is assigned to your account and you're not on it yet. |

### Usage cards

Three cards below the plan, one per thing a plan meters. Each shows what you've used this billing period against what's available to you, which is what the plan includes plus anything you bought on top, and each carries a **Buy** button when that kind of top-up is on sale for your plan.

| Card | What it measures |
|------|------------------|
| Credits used this period | Billed credits: successful requests only. Spent credits from failed requests are never charged. |
| Bandwidth used this period | All traffic, standard and premium. A plan without a bandwidth cap reads **No cap on this plan**. |
| Premium traffic this period | The part of your bandwidth served through a premium exit, which you get by sending `exitClass: premium`. When the included amount runs out, requests keep working on the standard pool and the response says `exitClass: standard`. |

Usage bars colour amber at 80% and red at or over the available amount. The Plan & Usage tab links to [Usage & Limits](/docs/dashboard/quota) for the per-product and per-key breakdown and every plan limit.

### Buying more

Click **Buy credits**, **Buy bandwidth**, or **Buy premium** on the matching usage card. The dialog prices the amount you enter on the server, shows subtotal, VAT and total, and charges a saved card or a new one entered right there. The allowance is yours a moment after the charge goes through.

What you buy lasts twelve months as a balance. Each period your plan's own allowance is used first, and only what you go over draws on the balance. A **Top-ups** box under the cards lists what you hold and until when. The box and the Buy buttons stay away entirely when your plan sells no top-ups, rather than showing refusals.

## Billing Details

The **Billing Details** tab holds the standing invoice profile applied to every future invoice:

- **Invoice email**: where PDF invoices are sent. Defaults to your account email.
- **Company name**: appears on invoices when set.
- **VAT / Tax ID**: EU VAT IDs are validated live against the VIES database. A green **Valid VAT** badge shows below the field once the check clears; an amber note shows if the format is right but VIES can't confirm the number.
- **Company representative**: the person who represents the company. Bulgarian invoices print it as MOL in the recipient box. Leave it empty if it doesn't apply to you.
- **Address**: street, city, postal code, and country. Country is a real dropdown.

Saved details apply to the next invoice you generate. An invoice that's already been issued keeps the details it was frozen with, with one exception: you can correct an invoice until the end of the month it was issued in. See [Correcting an Invoice](#correcting-an-invoice).

## Payment Methods

Manage the cards on file for your account.

- **View cards**: every saved payment method with card brand, last four digits, and expiry.
- **Add a card**: click **Add Payment Method** to open the card entry form. The card is stored with the payment provider.
- **Set default**: click the menu on any card and choose **Set as Default**. The default card is used for all future charges.
- **Remove a card**: click the menu on any card and choose **Delete**. You can't delete your only payment method while you have an active subscription.

## Invoices

The Invoices tab lists every invoice on your account.

| Column | Description |
|--------|-------------|
| Invoice | The invoice number |
| Date | When the invoice was issued |
| Amount | Total charged |
| Status | Paid, open, or void |
| PDF | Download link for the invoice PDF |
| Actions | Refund (paid invoices only), and **Update details** while the invoice is still correctable |

### Correcting an Invoice

An invoice freezes your billing details at the moment it's issued. If you fix a typo in your company name or add a VAT ID afterwards, the invoice that already went out still shows the old values.

You can correct it, but only until the end of the month it was issued in.

- If your current billing profile differs from what the invoice froze, the row shows an **Update details** button.
- If the invoice is still inside its window but there's nothing to change, the row reads **Editable until** with the date instead, so you can see the window exists before you need it.
- After that date the invoice is final.

Click **Update details** and a dialog lists exactly which fields change and what they change from. The invoice number, the dates, and the amounts never move. Confirming is your explicit consent to the correction, and it's recorded.

If your change adds or edits a tax ID, the dialog says so: a tax ID can change how VAT applies to a sale, so that case gets a human look and we get in touch if anything needs adjusting.

### Requesting a Refund

Click **Refund** on any paid invoice and confirm the dialog. Full refunds are processed immediately against the card that paid the invoice; the amount lands back on your statement within your card issuer's usual window. Partial refunds aren't a self-service action; contact support if you need one.

## Upgrading Your Plan

Click **Upgrade** from the Plan & Usage tab (or from the upgrade prompt on the Overview page) to open the plan picker.

The picker includes:

- **Public plans tab**: side-by-side comparison of the standard plans with features and pricing.
- **Your custom plans tab**: only appears if support has assigned one or more custom plans to your account.
- **Billing interval toggle**: monthly or annual. The annual badge shows the exact saving for the plan in view, computed from the two prices. A plan sold at one interval only shows that interval and no toggle.
- **Card entry**: if you don't have a card on file, you enter one here.
- **Proration preview**: when switching between paid plans, you see the exact prorated amount (or credit) before confirming.

If you don't have an active subscription, **Upgrade Plan** opens the same picker so you can subscribe directly.

After you confirm, your new plan takes effect immediately.

## Confirming a Plan FourA Placed You On

Support can place your account on a plan from an agreed date, so the plan's limits apply before any money moves. Until you pay, the Plan & Usage card shows **Confirm *plan*** with the monthly price. Click it and the checkout page reads **Confirm your plan**: your plan is already active, and you choose how to pay for it. Pick monthly or annual, enter a card if you have none on file, and the button charges the full period (**Confirm and pay**).

A placed plan that carries no charge needs no confirmation. It's simply yours.

## Changing Plans

To switch between paid plans, go to **Billing > Plan & Usage** and click **Change plan**. You see the same picker as the upgrade flow, including proration. Each plan is priced at the interval it's sold at, and a plan sold at one interval only says so (**sold annually only**) rather than quoting a price it doesn't have.

- **Upgrades** apply immediately with a prorated charge on today's card.
- **Downgrades** apply at the end of the current billing period.

If your bank asks for 3D Secure on the proration charge, the dialog hands you the authentication step before anything changes. The new plan lands once you finish it, not before. Close that step without completing it and you stay on your current plan.

## Canceling

Click **Cancel** on the Plan & Usage tab. You can optionally provide a reason.

After canceling:

- Your plan stays active until the end of the current billing period.
- You won't be charged again.
- You can resume before the period ends by clicking **Resume** on the Plan & Usage tab.

## Related

- [Dashboard Overview](/docs/dashboard/overview): Real-time stats and navigation
- [Usage & Limits](/docs/dashboard/quota): Every plan limit vs your current usage
- [Rate Limits](/docs/api/rate-limits): What the API answers when an allowance runs out
- [API Keys](/docs/dashboard/api-keys): Manage your keys
- [Metrics](/docs/dashboard/metrics): Request analytics and usage breakdown

---

#### Organizations
URL: https://foura.ai/docs/dashboard/teams-and-orgs

An organization groups API keys under one owner so several people can share them. Everything an organization's keys spend counts against the plan of whoever owns the organization, not against the person who fired the request.

## Where to Find It

Sign in to the [dashboard](https://foura.ai/dashboard) and open **Organizations** in the sidebar. Every organization you belong to is a row:

| Column | What it shows |
|--------|---------------|
| Organization | The name. Click it, or **Open**, to go to the organization's own page. |
| Your role | Owner, Admin, or Member |
| Members | How many people are in it, the owner included |
| Keys | How many API keys the organization owns |
| Created | When it was created |

## Creating an Organization

Click **New organization**, enter a name between 2 and 60 characters, and confirm. You become the owner. The name has to contain at least one letter or digit, and you can't have two organizations with the same name.

Creating an organization needs a plan that covers more than one person. The **Organizations you own** row on [Usage & Limits](/docs/dashboard/quota) shows whether yours does.

## Roles

There are three, and every organization has exactly one owner.

| Role | What it can do |
|------|----------------|
| Member | Create and use the organization's API keys, rename them, and see the organization's members and teams |
| Admin | Everything a member can do, plus add and remove people, change their roles, manage every organization key, and rename the organization |
| Owner | Everything an admin can do, plus hand the organization over to someone else. The owner carries the plan every organization key bills against. |

The owner can't be removed, can't leave, and can't be demoted. Ownership moves one way: by transfer.

Being in the organization is what grants access to its keys. A member with no admin rights can still create a key the company pays for, which is the point: a developer writing collectors shouldn't need a personal key that quietly bills them instead of the company.

## The Organization Page

**Open** on any row takes you to that organization's page. Five cards sit at the top: Members (with the owner, admin, and member split underneath), Your role, Owner, API keys, and Teams. Below them, two tabs:

- **Members**: the people in the organization, plus the controls your role gives you.
- **Teams**: the teams you belong to inside this organization, read-only.

Owners and admins also get a **Rename** button in the page header.

## Adding People

Owners and admins get an **Add a member** card above the Members table. Enter an email address, pick **Member** or **Admin**, and submit.

What happens next depends on the address, and the dashboard tells you which it was:

- The address already has a FourA account: they join immediately and get an email naming the organization, who added them, and what their role can do.
- The address doesn't: FourA emails them an invitation and they join the moment they sign in with that address. Nothing to click, and the invitation works whether they sign up fresh or already had an account they'd never opened.

Invitations expire after 14 days. Re-adding the same address refreshes the pending invitation instead of stacking a second one.

The owner gets an email whenever somebody joins, because the new person spends the owner's credits. Nobody gets an email confirming their own action.

### Pending Invitations

While at least one invitation is open, an **Invitations** table sits above Members, visible to owners and admins. It lists the address, the role waiting for them, who invited them, and when. Expired invitations stay listed and are marked, so you can see why nobody arrived. Use the action on the row to withdraw one.

## Changing a Role

Owners and admins change a member between **Member** and **Admin** with the dropdown in the Role column. Three rules:

- You can't change your own role. Ask another admin, or leave.
- The owner's role isn't editable here. Use **Make owner** instead.
- Every change asks first and says what the person will be able to do afterwards.

## Removing Someone, and Leaving

Owners and admins get **Remove** on every row but their own and the owner's. Your own row carries **Leave** instead, whatever your role.

Removing someone takes them out of the organization's teams too, so they immediately stop seeing its keys. It doesn't touch the keys themselves: an organization key belongs to the organization, not to whoever made it.

The owner can neither be removed nor leave. Hand the organization over first.

## Handing the Organization Over

Only the owner can do this. On the Members tab, click **Make owner** on the person taking over and confirm.

The organization moves to their plan: from that moment every request its keys make counts against their credits, their limits, and their invoice. The outgoing owner becomes an admin and keeps everything an admin can do.

## Which Keys You See

Every key an organization owns is visible to everyone in the organization. What differs is what you may do with it:

| Action | Member | Admin | Owner |
|--------|--------|-------|-------|
| Use the key, reveal it, create new organization keys | Yes | Yes | Yes |
| Rename it, edit its description | Yes | Yes | Yes |
| Regenerate, disable, delete, edit the IP allowlist or expiry | No | Yes | Yes |
| Move the key out of the organization | No | No | Yes |

Renaming a key is harmless. Regenerating or disabling one stops every colleague using it the instant it happens, which is why those sit with admins. Moving a key out takes the asset out of the company and moves its usage onto the taker's own plan, which is why that sits with the owner alone.

See [Managing API Keys](/docs/dashboard/api-keys) for the full walkthrough.

## The Owner Filter

Once you belong to an organization, an **Owner** dropdown appears above Overview, Metrics, Activity, and API Keys. It has three kinds of option: **Everything**, **Personal**, and one entry per organization. The choice sticks between visits and applies to every one of those four pages.

[Usage & Limits](/docs/dashboard/quota) and [Billing](/docs/dashboard/billing) deliberately don't take the filter. They answer "what bills to me", which is a different question from "what can I see": a member never sees the owner's quota.

## Billing Attribution

Every request made with an organization-owned key bills the **organization owner**, whoever fired it. That's the whole reason to move a key into an organization: it changes who the usage counts against for credits, plan limits, and invoices.

The owner's [Usage & Limits](/docs/dashboard/quota) page counts organization keys alongside their personal ones, and splits the two so it's clear where the spend came from.

## Teams

Every organization gets a default team called **Everyone**. New keys are filed into it automatically and everyone who joins the organization is added to it, which is what makes membership give access to the keys.

The Teams tab lists the teams you belong to, with your role in each and their member and key counts. Creating and editing teams isn't in the dashboard yet.

## Related

- [Managing API Keys](/docs/dashboard/api-keys): Create, transfer, and manage keys inside an organization
- [Usage & Limits](/docs/dashboard/quota): Team members, organizations, and what your plan allows
- [Billing & Subscriptions](/docs/dashboard/billing): How the owner's plan covers organization-key usage
- [Dashboard Overview](/docs/dashboard/overview): All dashboard sections

---

#### Account Settings
URL: https://foura.ai/docs/dashboard/account-settings

The Settings page lets you manage your profile, security, connected services, and active sessions. Open it from the sidebar in the dashboard.

## Profile

Update your display name and company. Changes sync across the platform.

| Field | Description |
|-------|-------------|
| Name | Your display name (shown in the dashboard and emails) |
| Company | Your company or organization name |

Email address changes aren't supported through the dashboard. Contact support if you need to update your email.

## Security

### Changing Your Password

If you signed up with email and password, you can change it here. Enter your current password and a new one (minimum 8 characters).

### Setting a Password (OAuth Users)

If you signed up with Google or another OAuth provider, you can set a password to enable email-based login as an alternative. No current password is required the first time.

### Password Reset

Click **Forgot Password** to receive a password reset link by email.

## Connected Services

View and manage OAuth connections (like Google). You can disconnect a service to remove it as a sign-in option. Make sure you have a password set before disconnecting your only OAuth provider.

## Sessions

View all your active sessions across devices. Each session shows:

| Field | Description |
|-------|-------------|
| Browser | Browser name and version |
| Operating System | OS name and version |
| Device | Device type |
| IP Address | Where the session originated |
| Last Used | When the session was last active |
| Expires | When the session automatically ends |

### Revoking Sessions

Revoke individual sessions or all sessions at once. Revoking a session signs that device out immediately. Your current session is marked so you don't accidentally sign yourself out.

## Related

- [Dashboard Overview](/docs/dashboard/overview): All dashboard sections
- [Authentication](/docs/getting-started/authentication): How API keys and authentication work

---

#### Playground
URL: https://foura.ai/docs/dashboard/playground

The Playground (sidebar > Playground) lets you run live API requests against your real key without writing any code. It's the fastest way to try a new target site, debug a tricky response, or compare Auto, Single, Proxy, and Browser side by side.

Open it at [foura.ai/dashboard#playground](https://foura.ai/dashboard#playground).

## What It Does

One form. Four engines. Real traffic.

- **Auto**: smart fetch. You pass a URL plus a `validate` rule and FourA picks the cheapest path that works.
- **Single**: direct HTTP fetch with realistic browser-like wire characteristics
- **Proxy**: managed rotating proxy fetch, optionally scoped to target-visible countries
- **Browser**: opens the URL in a Chrome browser instance for JS-rendered sites

Requests run against the API key you pick at the top of the page. Usage counts against that key's quota the same way a production call would, so don't burn through your plan in testing.

## Picking a Key

The API key dropdown shows every active key within your scope: personal keys, org keys you administer, and team-shared keys you can access. Pick the one you want the request to bill against. If you don't have any active keys yet, an inline prompt links you to the **API Keys** page to create one.

## Choosing a Mode

A top **Mode** row toggles between **Auto** and the manual engines. When Auto is selected, the form switches to the minimal Auto surface (URL plus `validate` plus a few knobs). When you switch off Auto, three pills appear: **Single**, **Proxy**, **Browser**. Switching pills swaps which fields are visible and which engine the request hits. The current selection is preserved when you reload the page.

| Mode | When to use it |
|------|----------------|
| Auto | New target or mixed-protection site. Auto picks the cheapest path and remembers what works. |
| Single | Fast HTTP fetch. Best first pick for a known host. |
| Proxy | Same fetch with automatic proxy rotation. Set `exitCountries` when you need a target-visible country. |
| Browser | Loads the page in a Chrome browser instance. Use when the data appears only after JavaScript runs. |

## Building the Request

### URL Row

The top row holds the HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), the target URL, and the **Send** button. Single, Proxy, and Auto honor every method. Browser ignores the method (Chrome always issues GET for navigation) and the body.

### Request Tabs

Below the URL row, five tabs let you fill in everything else:

| Tab | What it controls |
|-----|------------------|
| UI | Form fields for timeouts, redirects, flags, proxy, browser-specific options, and validate rules |
| Body | Free-form body for POST / PUT / PATCH requests |
| Headers | Custom request headers as key-value pairs |
| Cookies | Cookies to send with the request |
| Raw | The exact JSON payload that will be sent, editable directly |

Whatever you change in UI / Body / Headers / Cookies is reflected in Raw. Editing Raw works too, with the other tabs updating to match. A red dot appears on any tab or collapsible section that holds a value different from the engine's defaults, so you can spot at a glance what you've customized.

### UI Pane Sections

The UI tab groups settings into collapsible sections. Empty fields fall back to the engine's schema default. Sections that don't apply to the current Mode are hidden.

- **Timeouts**: `timeout_ms`, `connect_timeout_ms`, `accept_timeout_ms`, `server_response_timeout_ms`, `dns_cache_timeout_sec`. Auto exposes only `timeout_ms` (the total budget).
- **Redirects**: toggle and set `followRedirects` (0-20). Single, Proxy, Auto. Browser follows redirects on its own.
- **Flags**: `unblocker` for Single, Proxy, and Browser (unblocker on Browser triggers the auto defense solver); `tryJsonData` and `returnBuffer` for Single and Proxy. Auto exposes `forceProxy` and `returnSession` instead.
- **Proxy**: pick a specific proxy ID for Single or Browser, or set `maxTries`, the Proxy outer timeout, `exitCountries`, `exitClass`, and `ignoreProxies` for the Proxy engine. Auto also exposes `ignoreProxies`. The `exitClass` select has three states: unset sends no field at all, `standard` says the request must never escalate, and `premium` lets it escalate to a premium exit when the standard pool is struggling. Unset and `standard` are different requests, so leave the select empty unless you mean one of the two. Premium needs a plan that includes premium exits: see [exitClass](/docs/api/endpoints#exitclass).
- **Browser profile**: three cascading dropdowns, **os**, **browser**, and **version**, listing what FourA can actually present. They show up in Single and Proxy mode. Leave them empty for the newest Chrome. Each select narrows the other two, so a combination that resolves to nothing never appears. The section needs Web Unblocker on: with it off no browser headers are sent, a profile would only half-apply, and the API refuses the request instead.
- **Browser**: browser-only options such as `checkStatus` and `checkText`.
- **Validate**: `validate.status` (status codes), `validate.headers` (header key-value rules), and `validate.data` (body accept / fail substrings, `|`-separated alternatives) accept / fail rules. Available for every Mode, including Auto.

### Exit Country Scoping (Proxy Mode)

The **exitCountries** field on Proxy accepts a comma-separated list of two-letter target-visible country codes (`CZ, GB`). Values are trimmed, uppercased, and deduplicated on submit. Selection is a strict allowlist: proxies with unknown exits are excluded and the request never falls back to another country. If the current pool has no match, the response returns `code: "no_eligible_proxy"` with the requested scope echoed back in `details.exitCountries`. Preserve the scope and retry later.

When a proxy call succeeds under scoping, the response strip shows `exit <CODE>` next to the proxy ID so you can verify the served country matches what you asked for.

### Toolbar Reset

The **Reset** button on the toolbar (next to **History** and **Saved**) clears the playground back to a clean slate. Because it's destructive, it opens a confirm dialog that lists exactly what will be wiped: all three product forms (Single, Proxy, Browser), any saved cookies in the jar, any carried proxies, and the current response. Saved presets and the selected API key are kept. Click **Reset everything** to confirm; anything else cancels.

## Sending and Canceling

Click **Send** to fire the request. The right column flips to a loading state with a spinner and a **Cancel** button while the call is in flight. Click Cancel (or hit the button again on mobile) to abort. A canceled request restores the idle placeholder with "Request canceled." instead of rendering an error.

The response card switches to the result the moment the request completes (or fails). Auto runs can take longer than the manual engines because the ladder may climb several rungs on a cold target.

## Reading the Response

The response column mirrors the request layout with its own tabs:

| Tab | What it shows |
|-----|---------------|
| Body | Parsed body. Switches between JSON, HTML, and Text views depending on what came back. |
| Headers | Response headers, one per line. |
| Cookies | Cookies returned by the target, in both parsed (host-grouped) and raw (Set-Cookie text) views. The parsed view shows an `HO` badge on host-only cookies; domain cookies are unmarked. |
| Raw | The full JSON envelope returned by the API. |

A meta strip above the tabs shows the upstream HTTP status, the total time, the proxy ID that handled the call, and (for a scoped Proxy call) the two-letter `exit <CODE>`. For Auto runs, the strip also shows which ladder rung delivered the response, how many sub-attempts were made, and the credits spent.

### What the Call Needed

A sentence under the meta strip says what carried the page, in words. For an Auto run it names the rung (a session FourA already had for the host, a plain request, a rotating proxy, a real browser, or a browser first and then a cheap replay), whether a challenge was solved, how many attempts it took, and what it cost.

When one of your plan's limits refused the call, the sentence says so first: "Stopped by your plan, not by the site", followed by which limit (today's browser requests used up, too many requests in flight, this period's credits spent, and so on) and a link to [Usage & Limits](/docs/dashboard/quota). The line is built from the `X-FourA-Limit` code the API returned, so a hard page that fails tells you whether the site stopped it or the plan did.

### Carry Values Between Runs

After any run that returned reusable session data, a small **Carry** control on the response toolbar shows what's available:

- **Auto** runs offer the full `session` triple (`proxy`, `cookies`, `userAgent`).
- **Browser** runs offer the response `userAgent`, plus the proxy ID if one was used.
- **Proxy** runs offer the returned proxy ID, the browser profile when the rotation picked one you didn't ask for, and the `exitClass` that served the call, so a premium answer can be sent straight back.

Click **Carry** and pick where to apply each value in one click: `userAgent` becomes a `User-Agent` header on Single or Proxy, and the proxy ID drops into the `proxy` field on Single or Browser. Fields that receive a carried value show the "modified" red dot so you can see what changed.

A carried **browser profile** fills the three os, browser, and version selects and turns Web Unblocker on, the same rule that applies when you pick a profile by hand. It's offered only once the profile catalogue has loaded, since the form is three selects and not an id field.

The profile is the one value that says the request which *worked* was not the request you typed: Proxy reports `profile` only when it moved to a browser family you didn't ask for. Replay without it and you replay the version that failed. See [Why a Proxy Request Ran Out of Tries](/docs/troubleshooting/proxy-attempt-report).

### Expand to Full Screen

The expand icon on the response toolbar lifts the response card out of the split layout and into a full-screen overlay. Use it for deep JSON trees, long Set-Cookie dumps, or wide HTML bodies where the half-width column gets cramped. The page itself stops scrolling while the overlay is open. Click the icon again (or press Escape) to collapse.

## The curl Reproducer

Below the response, a curl block shows the exact command line equivalent of the request you just built. Copy it to repro the request from a terminal, share it with a teammate, or paste it into a bug report.

For revealable keys, a **Reveal key** button next to the snippet drops the real plain-text key straight into the curl so you can copy-and-run as is. Click again to hide. Legacy keys (created before the reveal feature shipped) keep a `PASTE_PLAINTEXT_FOR_<key-name>` placeholder; regenerate the key from the **API Keys** page to make it revealable.

The reveal is audit-logged on the server every time, and the plain key only lives in memory for the current page session.

## Saving Presets

If you find yourself reconfiguring the same target repeatedly, save it. Click **Save** on the request tabs row to store the current configuration as a named preset.

Open **Saved** in the toolbar to browse, rename, or delete your presets. Click any preset to load it back into the form.

| Preset field | What it stores |
|--------------|----------------|
| Name | A short label (up to 100 characters) |
| Description | Optional notes (up to 500 characters) |
| Endpoint | Which engine the preset is for (auto / single / proxy / browser) |
| Config | The full request payload, including UI fields, headers, cookies, and body |

Presets are scoped to your user account and aren't shared with team members.

## Replaying from History

Every request you run is logged. Open **History** in the toolbar to see your last 20 runs, sorted newest first.

Each row shows the endpoint, target URL, status, and time. Click **Replay** on any row to load that request back into the form, then **Send** to run it again.

History is automatically scoped to your account: you only see your own runs.

## Opening from Activity

The [Activity Log](/docs/dashboard/activity-log) detail dialog has an **Open in Playground** button. Click it and the Playground loads with both the archived request and the archived response. The form fills in from the stored payload, and the response card shows what the API returned at that moment with an "archived" badge on the proxy meta strip ("archived <time> [, truncated] [, via <proxy>]").

From there you can change a parameter and hit **Send** to run a new request against the live API, or just inspect the archived payload without re-running it. Payloads are kept for 24 hours, so older Activity rows won't have a reloadable response.

## Tips

- Start in Playground before writing code against a new target. With Auto on, you'll know within seconds whether a cheap fetch is enough or whether the site forces a browser solve.
- For country-locked targets, run one Proxy call with `exitCountries` set, then carry the returned proxy ID into a Browser call so the JavaScript render happens through the same exit.
- Save a preset for every target you scrape regularly. Replaying a saved preset takes one click; reconstructing the request from memory takes longer.
- Use the Cookies tab to debug session-based scraping. The raw Set-Cookie view shows exactly what the target sent.
- When a target refuses you, try another entry in the Browser profile selects before reaching for a heavier engine. Swapping the presented browser is free; a browser render isn't.
- Playground requests are billed against the key you pick. Use a dedicated low-quota key for casual exploration if you want to keep production usage clean.

## Related

- [API Endpoints](/docs/api/endpoints): Full parameter reference for all four engines, including `exitCountries` and the browser profile fields
- [Smart Fetch (Auto)](/docs/guides/smart-fetch): What Auto does under the hood
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): When to pick Auto vs Single vs Proxy vs Browser
- [API Keys](/docs/dashboard/api-keys): Manage the keys you authenticate Playground requests with
- [Activity Log](/docs/dashboard/activity-log): Open a past request straight into Playground
- [Dashboard Overview](/docs/dashboard/overview): All sidebar sections

---

#### Proxy Users
URL: https://foura.ai/docs/dashboard/proxy

The Proxy page (sidebar > Proxy, under **Access**) is where you create proxy users and get the exact connection string to paste into any client that accepts a proxy URL. It fronts the [proxy port](/docs/api/proxy-port): your traffic leaves from one of FourA's exits, with the network, country, and session behaviour you choose.

**Beta.** The sidebar entry carries a Beta badge, and a note above the list says why: traffic through the proxy port isn't billed yet, it isn't covered by monitoring or an uptime commitment, and option names can still change.

## Creating a Proxy User

1. Open **Proxy** in the sidebar.
2. Click **Create proxy user**.
3. Give it a name (up to 60 characters). The name is only for you to tell them apart.
4. Click **Create**.

A dialog shows the generated username and password with a copy button on each. You choose neither: the username has to stay free of dashes, because a dash starts an option in the [username grammar](/docs/api/proxy-port#options-ride-in-the-username), and the password is a strong random string. Both can be shown again later, so there's nothing to write down.

Proxy users are personal in this version. They can't yet be shared through an [organization](/docs/dashboard/teams-and-orgs).

## The List

| Column | What it shows |
|--------|---------------|
| Name | The name you gave it |
| Username | The credential half of the proxy username |
| Targeting | In words, what this user answers by default: network, country, and anything saved under Targeting |
| Status | Active or disabled |
| Created | When it was created |
| Last Used | When it last carried traffic, to the minute |

Each row has three buttons and a menu:

- **Connection string** opens the user's own page (see below).
- **Show password** reveals the password in a dialog.
- **Disable** stops the user authenticating within a minute; **Enable** brings it back.
- The menu holds **New password**, which keeps the username and replaces the password (anything still using the old one stops working immediately), and **Delete**, which removes the user for good.

## The Connection String Page

Click **Connection string** on a row and the page shows that user alone, with two tabs.

### Connection string tab

The lines to paste, rewritten live as you change anything under Targeting. Pick the format from the select on the right:

| Format | Shape |
|--------|-------|
| URL | `http://user:password@proxy.foura.ai:34004` |
| host:port:user:pass | `proxy.foura.ai:34004:user:password` |

The password is masked until you click **Show password**; **Copy** on a line always copies the real one. Under the lines, a sentence says what the string will do in words (for example "Residential, DE, Sofia, 10 min"), and curl, Python, and Node snippets show the first line in use.

With **Sticky** sessions and a count above one, the tab lists one line per address, each with its own generated session name. **New names** regenerates the whole list, which is a fresh set of addresses when a target has soured on the old ones, and **Copy all** copies every line.

### Targeting tab

Two cards, and the settings live inside the one you pick:

- **Shared network**: FourA's own exits, included in your plan. Choose a **Country** (the shared network is chosen by country and nothing finer). Tick **Use a residential exit if the shared network cannot carry the request** to arm the fallback; it only fires when your plan includes premium traffic and allowance remains, and it's unticked by default.
- **Residential network**: home addresses, drawn from your plan's premium traffic. **Country** opens **Region** and **Network (ASN)**, and a region opens **City**. **Device** narrows to Windows, Android, iOS, or macOS.

Below both cards, the session controls apply whichever network you picked:

| Control | What it does |
|---------|--------------|
| Session type | **Rotating** gives a new address per connection. **Sticky** keeps one. |
| How many | Sticky only. One line per address, up to 100 on this screen. |
| Session name | Sticky only, for a single address. Connections sharing a name share an address. Left empty, a name is generated. |
| Rotating interval | Sticky on the residential network only. How long one address is held, in minutes or hours, from 3 minutes to 24 hours. |

Country lists come from the exits FourA actually has, so a country that's offered has addresses behind it.

### Saving defaults

Everything on the Targeting tab applies to the connection string on screen only, until you click **Save as defaults**. Saved targeting becomes what the proxy user answers on every connection, the Targeting column on the list says so in words, and the connection string shrinks to the bare credential plus whatever differs from the saved values. Anything you add to the username still wins for that one connection.

A save is refused when the combination can't work, such as a city on the shared network or a fallback on the residential network, so a proxy user can't be stored in a state that refuses every connection.

## Tips

- Give each job its own proxy user. A user in daily use shows it in **Last Used**, and a leaked one can be disabled or given a new password without touching the others.
- Driving a browser through the port? Use a sticky session. A page load opens dozens of connections, and without a session each one would leave from a different address.
- The `host:port:user:pass` format is what most proxy managers import. The URL format is what curl and HTTP libraries take.
- Bytes through the port show up under Bandwidth on [Usage & Limits](/docs/dashboard/quota), with residential traffic counted as premium.

## Related

- [Proxy Port](/docs/api/proxy-port): Host, port, every username option, response codes, and limits
- [Usage & Limits](/docs/dashboard/quota): Bandwidth and premium traffic against your plan
- [Managing API Keys](/docs/dashboard/api-keys): The other kind of credential, for the JSON API
- [Dashboard Overview](/docs/dashboard/overview): All sidebar sections

---

### Getting Started

#### Quick Start
URL: https://foura.ai/docs/getting-started/quick-start

Go from zero to your first data collection in under two minutes.

## Prerequisites

- A FourA account ([sign up here](https://foura.ai))
- Your API key (create one in the [Dashboard](https://foura.ai/dashboard))

## Step 1: Get Your API Key

Sign in to the [Dashboard](https://foura.ai/dashboard) and create an API key. It looks like this: `pk_live_a1b2c3d4e5f6...`

Copy it. You'll need it for every request.

## Step 2: Make Your First Request

Open a terminal and run this (replace `YOUR_API_KEY` with your actual key):

```bash
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"}'
```

This sends an HTTP request to `example.com` and returns the page HTML.

## Step 3: Read the Response

```json
{
  "status": 200,
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html; charset=UTF-8",
      "content-length": "1256"
    }
  ],
  "data": "<!doctype html><html>...</html>",
  "total_time": 0.45
}
```

The `headers` field is an array of objects, one per redirect hop. Each entry has a `result` field with the status line plus every response header the target returned for that hop.

Key fields:
- `status`: HTTP status code from the target site
- `data`: the response body (HTML, JSON, or raw text)
- `total_time`: request duration in seconds

## Step 4: Try Different Endpoints

FourA has four endpoints for different situations:

| Endpoint | Speed | Use when |
|----------|-------|----------|
| `POST /api/auto/` | Varies (fast on warm hosts) | You don't know which engine the site needs. Pass a URL and let FourA pick the cheapest path that works. |
| `POST /api/single/` | Fastest (200ms-2s) | Static pages, APIs, server-rendered sites |
| `POST /api/browser/` | Medium (2s-10s) | JavaScript-heavy pages, SPAs, dynamic content |
| `POST /api/proxy/` | Fast (1s-5s) | Sites with bot detection, geo-restricted content |

Try an auto request (the smart default):

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

Try a browser request:

```bash
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", "timeout_ms": 15000}'
```

Try a proxy request (automatic proxy rotation):

```bash
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,
    "request": {
      "method": "GET",
      "url": "https://example.com",
      "unblocker": true
    }
  }'
```

## What's Next

- [Authentication](/docs/getting-started/authentication): API key management and security
- [API Endpoints](/docs/api/endpoints): Full parameter reference for all four endpoints
- [Smart Fetch (Auto)](/docs/guides/smart-fetch): How the auto endpoint decides what to do
- [SDKs and Libraries](/docs/getting-started/sdks-and-libraries): Examples in Python, Node.js, Go, Ruby
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): When to pick auto, single, browser, or proxy

---

#### Authentication
URL: https://foura.ai/docs/getting-started/authentication

# Authentication

Every request to the FourA API requires authentication. This page explains how to get, use, and manage your API key.

## Getting Your API Key

1. Sign in to the [FourA Dashboard](https://foura.ai/dashboard)
2. Go to the **API Keys** page
3. Click **Create Key**
4. Copy the key from the confirmation dialog

Your API key looks like this: `pk_live_a1b2c3d4e5f6...`

Keys created today are revealable: click the eye icon on the key's row later to bring the full secret back on demand (see [Managing API Keys](/docs/dashboard/api-keys) for the reveal flow and permissions). Legacy keys created before reveal shipped can't be brought back and show a lock icon; regenerate them once to switch over.

## Using Your API Key

Include your API key in the `X-API-Key` header of every request:

```bash
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"}'
```

In Python:

```python
import requests

response = requests.post(
    "https://eu.api.foura.ai/api/single/",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={"method": "GET", "url": "https://example.com"}
)
```

In Node.js:

```javascript
const response = await fetch('https://eu.api.foura.ai/api/single/', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ method: 'GET', url: 'https://example.com' })
});
```

## API Key Security

Treat your API key like a password:

- **Don't commit it to version control.** Use environment variables instead.
- **Don't expose it in client-side code.** Only use it in server-side applications.
- **Rotate if compromised.** Regenerate the key from the Dashboard. The old secret stops working immediately, and every reveal is audit-logged so a stolen credential is easy to spot after the fact.

### Using Environment Variables

Store your key in an environment variable:

```bash
export FOURA_API_KEY="pk_live_a1b2c3d4e5f6..."
```

Then reference it in your code:

```python
import os
api_key = os.environ["FOURA_API_KEY"]
```

```javascript
const apiKey = process.env.FOURA_API_KEY;
```

## Common Authentication Errors

All authentication failures return a `401 Unauthorized` status.

| Error | Message | Cause | Fix |
|-------|---------|-------|-----|
| 401 | Missing API key. Include X-API-Key header. | No `X-API-Key` header in the request | Add the `X-API-Key` header |
| 401 | Invalid API key | Wrong key, extra whitespace, or deactivated key | Verify the key, trim whitespace, or create a new key from the Dashboard |

Every response, success or failure, carries an `X-Foura-Request-Id` header. Log it on your side so support can look up a specific call later.

## Next Steps

- [Quick Start](/docs/getting-started/quick-start): Make your first request
- [Managing API Keys](/docs/dashboard/api-keys): Reveal, edit, regenerate, and delete keys
- [API Endpoints](/docs/api/endpoints): Full endpoint reference
- [Error Handling](/docs/api/errors): Handle authentication errors gracefully

---

#### SDKs and Libraries
URL: https://foura.ai/docs/getting-started/sdks-and-libraries

FourA is a REST API: you can use it with any language that speaks HTTP. Here are quick-start examples in the most popular languages.

## Python

Using the `requests` library:

```python
import requests

response = requests.post(
    "https://eu.api.foura.ai/api/single/",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "method": "GET",
        "url": "https://example.com"
    }
)

data = response.json()
print(data["data"][:200])  # First 200 chars of response body
```

## Node.js

Using the built-in `fetch` (Node 18+):

```javascript
const response = await fetch('https://eu.api.foura.ai/api/single/', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    method: 'GET',
    url: 'https://example.com'
  })
});

const result = await response.json();
console.log(result.data.slice(0, 200));
```

## cURL

The simplest way to test from the command line:

```bash
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"}'
```

## Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    payload, _ := json.Marshal(map[string]string{
        "method": "GET",
        "url":    "https://example.com",
    })

    req, _ := http.NewRequest("POST", "https://eu.api.foura.ai/api/single/", bytes.NewBuffer(payload))
    req.Header.Set("X-API-Key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

## Ruby

```ruby
require 'net/http'
require 'json'
require 'uri'

uri = URI('https://eu.api.foura.ai/api/single/')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['X-API-Key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = { method: 'GET', url: 'https://example.com' }.to_json

response = http.request(request)
puts JSON.parse(response.body)['data'][0..200]
```

## MCP Server (for LLM agents)

If you're building an LLM agent (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code), skip the raw HTTP client and use the [`@fouradata/mcp` server](/docs/mcp/server). It exposes all four FourA endpoints as native [Model Context Protocol](https://modelcontextprotocol.io) tools (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) with typed responses, so the agent can pick the right method without you writing any glue code.

Minimum config for Claude Desktop:

```json
{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": { "FOURA_API_KEY": "pk_live_..." }
    }
  }
}
```

Full setup for every supported client: [MCP Server](/docs/mcp/server).

## Next Steps

- [Quick Start](/docs/getting-started/quick-start): Your first request
- [Authentication](/docs/getting-started/authentication): Get your API key
- [API Endpoints](/docs/api/endpoints): Full reference
- [MCP Server](/docs/mcp/server): Use FourA as an MCP toolset

---

### Guides

#### Choosing the Right Endpoint
URL: https://foura.ai/docs/guides/choosing-task-type

FourA offers four request endpoints, each optimized for a different scenario. Choosing the right one saves time, reduces cost, and improves success rates.

## Quick Decision Guide

**Use the auto endpoint when:**
- You're targeting a new site and you don't yet know what it needs
- You want one call that handles direct, proxy-rotated, and browser fallbacks for you
- You want a session you can replay cheaply on the next call to the same host

**Use the single endpoint when:**
- The page is server-rendered (no JavaScript required)
- You need maximum speed (typically under 1 second)
- You're hitting APIs or static HTML pages from a host you already know works

**Use the browser endpoint when:**
- The page relies on JavaScript to render content
- Content loads after the initial page load
- You need the fully rendered DOM

**Use the proxy endpoint when:**
- The target site actively blocks requests
- You need to rotate through multiple IP addresses
- Previous attempts returned 403 or captcha pages

## Endpoint Comparison

### Auto (`POST /api/auto/`)

The smart-fetch endpoint. You pass a URL and (ideally) a `validate` rule, and FourA walks a cost-aware ladder: cheap direct probe, rotated proxy, full browser. The first rung that returns a response matching your `validate` wins. On repeat calls to the same host, a warm session is replayed, so the second call is cheap.

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

**Typical response time:** 200ms (warm) to 30s+ (cold solve on a hard site)
**Best for:** New targets, mixed-protection sites, "I just want the page"

For a deeper walkthrough, see the [Smart Fetch guide](/docs/guides/smart-fetch).

### Single (`POST /api/single/`)

The fastest option. Sends an HTTP request with realistic browser-like wire characteristics, without spinning up a browser process.

```bash
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/api/products"}'
```

**Typical response time:** 200ms to 2s
**Best for:** APIs, news sites, blogs, static product pages

### Browser (`POST /api/browser/`)

Opens your URL in a Chrome browser instance. The page loads completely, JavaScript executes, and you get the final rendered HTML.

```bash
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": "data-table"
  }'
```

**Typical response time:** 2s to 10s
**Best for:** Single-page apps (SPAs), sites with lazy loading, JavaScript-rendered content

### Proxy (`POST /api/proxy/`)

Combines HTTP requests with automatic proxy rotation. If the first attempt fails or gets blocked, FourA retries through different proxies.

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

**Typical response time:** 1s to 5s
**Best for:** E-commerce price monitoring, travel aggregation, sites with bot detection

## Auto vs Manual

When should you let auto pick, and when should you call Single, Proxy, or Browser yourself?

| Pick auto | Pick manual |
|-----------|-------------|
| You don't know what the site needs yet | You know exactly which engine the target wants |
| You want one call that just works | You're optimizing the request shape for a known target |
| You're fine with auto reusing a session it learned | You want full control over per-call retry, timeout, and proxy choice |
| You're paying for a few seconds of probing on the first call | Latency on the first call matters more than discovery |

Auto isn't always the cheaper pick. If you already know a target works with Single and `unblocker` on, calling Single directly skips the probe and costs 2 credits. Auto on the same target costs whatever its ladder spends.

## When to Combine Approaches

Some workflows benefit from using multiple endpoints:

1. **Discover with auto**: pass a `validate` rule and let the ladder figure out which rung the site needs.
2. **Replay with single**: take the `session.proxy`, `session.cookies`, and `session.userAgent` auto returned, then call Single with them for follow-up pages on the same host.
3. **Fall back to browser**: if single starts failing, switch to browser rendering.
4. **Add proxy**: if you're getting blocked (403 / captcha) without auto, wrap your request in the proxy endpoint for automatic rotation.

This progressive approach keeps cost low while keeping success rates high.

## Performance Tips

- Pass a `validate.data.accept` substring on protected targets. Without it, auto can't tell a real page from a challenge interstitial.
- Use the single endpoint by default for known-working hosts and only upgrade when needed.
- Set `checkText` in browser requests to avoid waiting for unnecessary content.
- Set `maxTries` in proxy requests to control retry behavior (default is 5, max is 90).
- Keep `timeout_ms` reasonable: 10 to 15 seconds for most pages, 30s+ for cold auto runs against protected sites.

## Next Steps

- [Smart Fetch (Auto)](/docs/guides/smart-fetch): The deep dive on `/api/auto/`
- [API Endpoints](/docs/api/endpoints): Full parameter reference
- [Scrape a Dynamic Website](/docs/how-to/scrape-dynamic-website): Step-by-step browser request guide
- [Quick Start](/docs/getting-started/quick-start): Your first request in 30 seconds

---

#### Handling Anti-Bot Protection
URL: https://foura.ai/docs/guides/anti-bot-protection

Modern websites use advanced bot detection. This guide explains how FourA handles anti-bot systems and how to maximize your success rate.

## How Bot Detection Works

Websites use several layers of protection:

- **IP reputation**: Data centers and known proxy addresses get blocked
- **Wire fingerprinting**: Each HTTP client has a unique handshake signature that sites can detect
- **Browser fingerprinting**: JavaScript checks for headless browser indicators
- **Behavioral analysis**: Request patterns, timing, and navigation flow
- **CAPTCHAs**: Visual challenges as a last line of defense

Common anti-bot providers include Cloudflare, DataDome, PerimeterX, and Akamai Bot Manager.

## Fastest Path: Auto

If you don't know the protection level yet, call `/api/auto/` with a `validate.data.accept` substring that only the real page carries. Auto walks a cost-aware ladder (cheap probe, rotated proxy, browser render, browser through proxy) and stops at the first rung that returns a response your rules accept. On repeat calls to the same host, a warm session is replayed instead, so the second hit is cheap.

```bash
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://protected-site.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'
```

Without `validate.data.accept`, auto can't tell a real 200 from a challenge interstitial returned with status 200 and may return the challenge as success. See the [Smart Fetch guide](/docs/guides/smart-fetch) for the full walkthrough.

## How FourA Helps at Each Layer

### Realistic Wire-Level Requests

The single endpoint (`POST /api/single/`) emits handshake characteristics that match a real browser. This passes the most common wire-level checks without the overhead of running a full browser.

Enable `unblocker` to also inject realistic browser headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). `unblocker` is on by default; set `false` only to send a plain client signature.

```json
{
  "method": "GET",
  "url": "https://protected-site.com/data",
  "unblocker": true
}
```

### Real Browser Rendering

The browser endpoint (`POST /api/browser/`) runs a full Chrome browser instance. Combined with anti-detection patches, it passes most JavaScript-based fingerprint checks. `unblocker` on Browser triggers the auto defense solver (Turnstile clearance and similar gates); leave it on unless you want the raw challenge page back.

### Proxy Rotation

The proxy endpoint (`POST /api/proxy/`) automatically rotates through residential and data center proxies. If one IP gets blocked, the next attempt uses a different one. Use `ignoreProxies` on a follow-up call to skip exits you already burned; use `maxTries` (default 5, max 90) to control how hard it works.

### Country-Scoped Exits

Pass `exitCountries` on `/api/proxy/` to restrict selection to proxies whose target-visible country matches a strict allowlist. Values are two-letter codes (`["CZ", "GB"]`), trimmed, uppercased, and deduplicated. FourA never falls back to an unrequested country; if the current pool has no match, the response returns `code: "no_eligible_proxy"` with the normalized scope in `details.exitCountries` so you can retry later without loosening the requirement.

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

The response includes `exitCountry` when scoping was requested. Verify it belongs to your allowlist before trusting the payload, then reuse the returned `proxy` ID on any follow-up Browser call so the JavaScript render happens through the same exit.

## FourA Tells You What Stopped You

You don't have to guess which system blocked a request. When a target runs a bot check, the response names it.

- `POST /api/single/` and `POST /api/proxy/` return a `defense` object: `defense.vendor` is the system, `defense.solved` says whether the check was cleared, and `defense.present` lists everything recognised on that response.
- `POST /api/browser/` returns `defenseSolved` plus `defenses.present` and `defenses.cleared`.

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "cookie": "_I_=<clearance>"
  }
}
```

Two rules follow from it:

1. **`solved: false` means the body may be the challenge, not the page.** FourA never dresses an unsolved challenge up as content, so check the flag before parsing.
2. **A solve hands you the clearance.** When `defense.cookie` is present, send it back as a `Cookie` header on the same exit with the same User-Agent and the follow-up requests skip the check entirely.

FourA recognises Cloudflare, SiteGround, DataDome, PerimeterX, Akamai, Incapsula, AWS WAF, hCaptcha, reCAPTCHA, and eBay's own challenge. Recognising is wider than clearing: a system we can name but not clear is reported and never changes what the request costs. See [Anti-Bot Defenses](/docs/api/anti-bot-defenses) for every field, the current clear-versus-detect split, and a replay example.

## Strategy by Protection Level

### Unknown Protection

Use auto. It probes cheap first and only escalates as far as the target forces it, so you pay for the discovery once per host.

### Low Protection (most sites)

Use the single endpoint with `unblocker`. The wire-level match is enough.

```bash
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://news-site.com/article", "unblocker": true}'
```

### Medium Protection (Cloudflare, basic WAF)

Use the browser endpoint to pass JavaScript challenges:

```bash
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://protected-site.com/data", "timeout_ms": 15000}'
```

### High Protection (DataDome, PerimeterX)

Use the proxy endpoint with multiple retry attempts:

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 10,
    "request": {
      "method": "GET",
      "url": "https://heavily-protected.com/prices",
      "unblocker": true
    }
  }'
```

For chained WAF challenges (Cloudflare "Just a moment", Vercel Security Checkpoint, Akamai Bot Manager) where you need the rendered page after the challenge clears, see the [MCP Recipes](/docs/mcp/recipes). The "Protected page: proxy first, browser when JavaScript is needed" recipe shows the exact proxy-then-browser handoff.

## Best Practices

1. **Start with auto for unknown targets.** Pass a `validate` rule, let the ladder pick the cheapest rung, then read `meta.rung` in the response to see which engine worked. Once you know, call that engine directly for repeat traffic.

2. **Reuse the winning session.** After an auto call, the returned `session` (proxy ID + cookies + userAgent) can be replayed through `/api/single/` or `/api/browser/` for follow-up pages on the same host, at Single's price.

3. **Respect rate limits.** Even with proxy rotation, sending hundreds of requests per second to a single site will trigger behavioral detection. Space your requests by at least 1 to 2 seconds.

4. **Keep `unblocker` on.** For Single, Proxy, and Browser requests, `unblocker: true` (the default) injects realistic browser headers automatically. Turn it off only when you specifically need a plain client signature or a raw challenge page.

5. **Monitor success rates.** Check the [Dashboard](https://foura.ai/dashboard) metrics to track your success rate over time. A sudden drop usually means the target site updated its protection.

6. **Skip burned exits.** If a `/api/proxy/` or `/api/auto/` call returned a proxy ID that then started failing, pass it in `ignoreProxies` on the next call so FourA picks a different exit.

7. **Read `defense` before you retry.** The vendor name tells you whether a different browser profile is worth trying, whether you need a full render, or whether the check is one nobody clears without a solving service.

8. **Change the browser you present.** Some targets accept one browser and refuse another. Set `browser`, `os`, or `version` on Single and Proxy, and read `GET /api/profiles` for the current catalogue. Details in the [endpoint reference](/docs/api/endpoints).

## What FourA Can't Bypass

Some scenarios require additional handling outside the API:

- **Login-protected content**: FourA doesn't manage long-lived logins for you. The browser endpoint accepts `cookies` per-request; carry your session cookies in yourself.
- **Interactive CAPTCHAs**: reCAPTCHA and hCaptcha need a solving service. FourA recognises both and reports them in `defense.present`, but doesn't clear them. Turnstile is handled by Browser.
- **Geo-restricted content**: use `exitCountries` on `/api/proxy/` to pin selection to allowed countries. Sites that additionally restrict by ISP or ASN (some country-licensed bookmakers, certain government services) may still block generic residential exits; the request returns `no_eligible_proxy` when the current pool has no matching exit.
- **Sites with legal restrictions**: Always ensure your data collection complies with the target site's terms of service and applicable laws.

## Next Steps

- [Smart Fetch (Auto)](/docs/guides/smart-fetch): Deep dive on `/api/auto/`
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): Decision guide for endpoints
- [Common Issues](/docs/troubleshooting/common-issues): Fix 403s and captcha blocks
- [API Endpoints](/docs/api/endpoints): Full parameter reference including `exitCountries`
- [Anti-Bot Defenses](/docs/api/anti-bot-defenses): The `defense` field, the vendor list, and clearance replay
- [MCP Recipes](/docs/mcp/recipes): Workflow templates including the proxy-first-then-browser chain

---

#### Smart Fetch (Auto)
URL: https://foura.ai/docs/guides/smart-fetch

You hand FourA a URL and a `validate` rule for what the real page should contain. FourA does the rest: it walks a cost-aware ladder, stops at the first rung that returns a response your rules accept, and remembers what worked per host so the next call on the same site is cheap.

This guide explains what auto does under the hood, when to use it, and how to read its response. For the parameter reference, see [API Endpoints](/docs/api/endpoints#smart-fetch-auto).

## The Idea

Most scraping setups make you pick the engine up front. Single is fastest, Proxy adds rotation, Browser handles JavaScript. You guess wrong, you waste credits or you get blocked.

Auto flips it. You declare success (`validate`), not method. FourA climbs a ladder until one rung succeeds:

1. **Cheap probe** (single, straight out of FourA's own network)
2. **Rotated proxy single**
3. **Browser**, with JavaScript and a solver if the site challenges
4. **Browser through proxy** for the hardest targets

Auto stops as soon as a rung returns a response your `validate` rule accepts.

One rung sits outside that order. When an exit reaches the site but the site refuses the deep URL you asked for, auto fetches the site's entry page through that same exit, keeps the cookies the entry page hands out, and asks for your URL again carrying them. That's the `warmup` rung. It only runs on a URL deeper than the site root, only after the direct attempt already failed, and it can only add an outcome, never take one away.

`forceProxy` defaults to `true`, so rung 1 is skipped and the target never sees FourA's own address. Most calls then finish on rung 2, or on a replayed warm session. Set `forceProxy: false` when you know a target treats a clean address better than a rotating one, and rung 1 comes back.

## What You Send

The minimum is a URL plus a `validate` substring. Without `validate.data.accept`, auto can't tell a real page from a challenge interstitial returned with HTTP 200, and it may return the challenge as success.

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

Optional knobs (see the [endpoint reference](/docs/api/endpoints#smart-fetch-auto) for full details):

- `returnSession` (default `true`): return the winning `{ proxy, cookies, userAgent }` so you can replay it.
- `forceProxy` (default `true`): skip direct-egress rungs. Set `false` only if you know the site is friendlier to a clean IP than to free rotating proxies.
- `timeout_ms` (default `120000`): total budget for the whole call. The ladder portions it across rungs.
- `ignoreProxies`: proxy IDs to avoid on every sub-attempt.
- `followRedirects` (default `5`): max redirects on the cheap rungs.

## What You Get Back

```json
{
  "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..."
  }
}
```

Three things to read:

- **`status` and `data`**: the same shape the underlying engine returned. `status` is the target's HTTP status, not the transport status of your call to FourA. For single and proxy rungs, `headers` is a per-hop array. For browser rungs, `headers` is a flat object.
- **`meta`**: the trace of what the ladder did, present on every response. `meta.rung` names the step that delivered the response, `meta.attempts` counts sub-call tries, `meta.solved` flags whether a bot challenge was cleared, and `meta.credits` is the total spend for the call (the same number as the `X-FourA-Credits` header).
- **`session`**: the `{ proxy, cookies, userAgent }` triple that cracked the target. Use it to replay against the same host via `/api/single/` or `/api/browser/`.

Auto answers with HTTP 200 whenever the ladder ran, even when every rung failed. Read `status` and `error` in the body to find out what happened, not the transport status code. A non-200 from `/api/auto/` means FourA rejected the call before the ladder started: 401 for a bad key, 400 for a bad body or a private target, 429 or 503 for the platform's shared limits. A plan limit met inside the ladder also comes back as HTTP 200, with the refusal in the body (see [When Your Plan's Limits Meet the Ladder](#when-your-plans-limits-meet-the-ladder)).

## Replaying with the Session

After auto returns a session, you can drop straight into Single or Browser for follow-up pages on the same host. No new ladder climb, no new probe.

```python
import requests

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

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])
```

The session is only as durable as the target makes it. Some sites bind clearance to the cookie jar for hours; others rotate every few minutes. If a replay starts returning challenges again, call `/api/auto/` once more to refresh.

## When to Use Auto

| Use auto | Use single, proxy, or browser by hand |
|----------|----------------------------------------|
| You're targeting a new site and don't know what it needs | You already know the engine that works |
| You want one call that handles direct, proxy, and browser fallback for you | You want full control over per-call retries and timeouts |
| You're fine paying a few seconds of probing on the first call | First-call latency matters more than discovery |
| You want a learned session you can replay cheaply | You're optimizing a tight loop on a known-good target |

Auto isn't always the cheapest pick. If you know a target works with `single` + `unblocker`, calling Single directly is 2 credits with predictable latency. Auto on the same target costs whatever its ladder spends, which can be more if the site requires escalation.

## Validate Tells Auto What "Success" Means

The single most important parameter is `validate`. Without it, auto can't distinguish a real 200 page from a 200 challenge interstitial dressed up as content.

Use `validate.data.accept` with a substring only the real page contains:

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

For JSON APIs, accept a field name you expect:

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

For sites that legitimately return non-200 (geo-blocks you want to ignore, intentional 403 on logged-out endpoints), allow them via `validate.status.accept`:

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

Without `validate`, auto falls back to "HTTP 200 = success" and won't catch a Cloudflare challenge interstitial that the WAF returns with a 200.

## Reading `meta.rung` to Understand What Happened

`meta.rung` is the most useful debug signal. Values:

- `probe` - solved on a cheap direct request. The cheapest path.
- `proxy` - needed proxy rotation to get through.
- `browser` - needed a full browser render, possibly with a challenge solve.
- `cache` - replayed a warm session from a prior auto call. Cheapest path on repeat calls.
- `warmup` - the site served its entry page but gated the deep URL, so auto fetched the entry page first, kept the cookies it handed out, and asked again with them. The session it stores from this rung isn't tied to one exit, so follow-up calls land on the cheap rungs.
- `fail` - no rung produced a response your rules accepted.

`meta.solved: true` means a bot challenge was detected and cleared during the call. `meta.attempts` is the count of sub-call tries before success. For the vendor detail behind a solve, read the `defense` field the single and proxy rungs return: see [Anti-Bot Defenses](/docs/api/anti-bot-defenses).

If a site keeps ending on `browser` when you expected `probe`, consider whether a stricter `validate` rule (or a less strict one) would let a cheaper rung pass. Remember that `forceProxy` defaults to `true`, so the direct-egress probe is skipped unless you turn it off.

## Errors and Edge Cases

When auto fails, the response carries `status` (usually the last failed rung's status) and an `error` string:

```json
{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}
```

`status: 0` means no rung produced a response at all (every attempt timed out or got rejected). A non-zero `status` plus `error` means the last attempt got a response, but auto rejected it (validate or otherwise).

Check `meta.attempts` and `meta.credits` to see where the budget went. If `meta.attempts` is high and `meta.rung` is `fail` after the browser rung, the target may need a longer `timeout_ms`, a stricter `validate` rule, or simply isn't reachable through rotating proxies right now.

### When Your Plan's Limits Meet the Ladder

Auto's sub-calls are ordinary Single, Proxy and Browser requests under your key, so your [plan limits](/docs/api/rate-limits) apply to them. The ladder reads the `X-FourA-Limit` code on a refusal and treats the two kinds differently.

**A shut rung leaves the rest of the ladder usable.** `plan_limit_browser_daily` (your Browser requests for the day are used up) and `plan_limit_concurrency` (that endpoint already has as many of your requests running as the plan allows) close one rung. Auto keeps working the other rungs, so you still get a page whenever a rotating exit or a warm session serves the content, and the exits it tried aren't blamed for a refusal that came from your own plan. Nothing is banned and no session is thrown away.

**An account that's out stops the ladder.** `plan_limit_credits`, `plan_limit_bandwidth`, `plan_limit_rate`, `plan_limit_feature`, and `plan_limit_premium` can't be helped by another rung, so auto returns at once instead of spending more of your credits proving it. The refusal comes back in the body with the sub-call's status and the same `reason` field the direct endpoints use:

```json
{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

The whole refusal body from the sub-call comes through, plus `status` and `meta`. Read `status` from the body and not the transport status: auto still answers HTTP 200 here, because the ladder ran. A `plan_limit_feature` or `plan_limit_premium` refusal arrives the same way with `status: 403`. A refused sub-call spends nothing, so `meta.credits` counts only the rungs that got as far as the target.

One auto call can hold several slots while its ladder climbs, so a parallel batch of auto calls reaches a concurrency ceiling with fewer calls than you'd expect. [Run Requests in Parallel](/docs/how-to/run-requests-in-parallel) covers sizing the batch.

## What Auto Does Not Do

- It does not bypass legal restrictions. If a site is geo-blocked and rejects every exit FourA can reach, auto returns the block.
- It does not cache content. Every call still hits the target. The "warm session" is the proxy and cookies, not the response.
- It does not write to the [Activity Log](/docs/dashboard/activity-log) as a separate row from the sub-calls. The Single / Proxy / Browser sub-calls auto made on your behalf appear in Activity; the outer `/api/auto/` call is a coordinator.

## Related

- [API Endpoints](/docs/api/endpoints#smart-fetch-auto): Full parameter reference
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): When to pick auto vs single, proxy, or browser
- [Request Outcomes](/docs/api/outcomes): Which outcomes are billable
- [Anti-Bot Protection](/docs/guides/anti-bot-protection): What FourA does about Cloudflare, DataDome, and friends
- [Anti-Bot Defenses](/docs/api/anti-bot-defenses): The `defense` field behind `meta.solved`
- [MCP Recipes](/docs/mcp/recipes): The same patterns as MCP tool calls
- [Rate Limits](/docs/api/rate-limits): The plan limits auto's sub-calls are measured against

---

### How To

#### Scrape a Dynamic Website
URL: https://foura.ai/docs/how-to/scrape-dynamic-website

Dynamic websites load content using JavaScript after the initial page load. This guide shows how to collect data from these sites using FourA's browser endpoint.

## The Problem

When you send a standard HTTP request to a JavaScript-heavy website, you get the HTML shell but not the actual content. The data you need (product listings, prices, search results) is loaded by JavaScript after the page renders in a browser.

This is increasingly common with modern frameworks like React, Vue, Angular, and Next.js.

## The Solution: Browser Requests

FourA's browser endpoint (`POST /api/browser/`) opens your URL in a Chrome browser instance that:
1. Loads the page
2. Executes all JavaScript
3. Waits for the content to render
4. Returns the fully rendered HTML

## Step 1: Identify What You Need

Before making the request, visit the target page in your browser and use DevTools (F12) to find a piece of text or element that confirms the content has loaded. For example:

- A product name that appears after JS renders
- A CSS class like `product-grid` in the rendered HTML
- A text string like "results" that only appears when data loads

## Step 2: Send a Browser Request

```bash
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/products",
    "timeout_ms": 15000,
    "checkText": "product-grid"
  }'
```

The `checkText` option tells FourA to verify that the string "product-grid" appears in the rendered page. If it doesn't appear before the timeout, the request fails, letting you know the content didn't load.

## Step 3: Parse the HTML

The response contains the fully rendered HTML in the `body` field. Parse it with your preferred library:

### Python (BeautifulSoup)

```python
import requests
from bs4 import BeautifulSoup

resp = requests.post("https://eu.api.foura.ai/api/browser/", headers={
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}, json={
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-grid"
})

html = resp.json()["body"]
soup = BeautifulSoup(html, "html.parser")

for product in soup.select(".product-card"):
    name = product.select_one(".product-name").text.strip()
    price = product.select_one(".product-price").text.strip()
    print(f"{name}: {price}")
```

### Node.js (cheerio)

```javascript
import * as cheerio from 'cheerio';

const resp = await fetch('https://eu.api.foura.ai/api/browser/', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://example.com/products',
    timeout_ms: 15000,
    checkText: 'product-grid'
  })
});

const { body: html } = await resp.json();
const $ = cheerio.load(html);

$('.product-card').each((i, el) => {
  console.log($(el).find('.product-name').text(), $(el).find('.product-price').text());
});
```

## Troubleshooting

**Still getting empty content?**
- Verify the page actually uses JavaScript rendering (check with "View Source" vs. DevTools)
- Increase `timeout_ms`: some pages load slowly
- Check if the page requires authentication or cookies (use the `cookies` parameter)

**Getting a captcha page?**
- For single/HTTP requests, switch to the proxy endpoint (`POST /api/proxy/`) for automatic IP rotation.
- To route a browser request through a proxy, pass the browser endpoint's `proxy` parameter. The proxy endpoint only wraps single/HTTP requests, not browser requests.

The `proxy` parameter takes the opaque proxy ID an earlier response returned, never a proxy address of your own. Run one `POST /api/proxy/` (or `POST /api/auto/`) call first, read the `proxy` field it returns, then pin it:

```bash
# Step 1: let FourA find a working exit. The response carries "proxy": "A1B2C3".
curl -X POST "https://eu.api.foura.ai/api/proxy/" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxTries": 5, "request": {"method": "GET", "url": "https://example.com/products"}}'

# Step 2: render through that same exit.
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/products", "proxy": "A1B2C3", "timeout_ms": 20000}'
```

Sending an address instead of an ID comes back as `400 Invalid proxy format`. The full pattern is in [Reuse a Proxy Across Requests](/docs/how-to/reuse-a-proxy).

## Next Steps

- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): When to use browser vs. single
- [Monitor Competitor Prices](/docs/how-to/monitor-competitor-prices): Full price tracking tutorial
- [Anti-Bot Protection](/docs/guides/anti-bot-protection): Handle protected sites
- [Reuse a Proxy Across Requests](/docs/how-to/reuse-a-proxy): Pin one exit across a whole workflow

---

#### Monitor Competitor Prices
URL: https://foura.ai/docs/how-to/monitor-competitor-prices

Set up automated price monitoring across competitor websites using the FourA API.

## What You'll Build

A Python script that:
1. Fetches product pages from a list of competitor URLs
2. Extracts price data from the HTML
3. Logs results to a CSV file
4. Runs on a schedule

## Prerequisites

- A FourA API key ([get one here](https://foura.ai/dashboard))
- Python 3.8+
- `requests` and `beautifulsoup4` packages

```bash
pip install requests beautifulsoup4
```

## Step 1: Define Your Targets

Create a list of product URLs to monitor:

```python
targets = [
    {"name": "Competitor A - Widget", "url": "https://competitor-a.com/widget", "selector": ".price"},
    {"name": "Competitor B - Widget", "url": "https://competitor-b.com/products/widget", "selector": "[data-price]"},
    {"name": "Competitor C - Widget", "url": "https://competitor-c.com/item/123", "selector": ".product-price span"},
]
```

## Step 2: Fetch Pages via FourA

```python
import requests
import time

SINGLE_URL = "https://eu.api.foura.ai/api/single/"
BROWSER_URL = "https://eu.api.foura.ai/api/browser/"
API_KEY = "YOUR_API_KEY"

HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

def fetch_page(url, use_browser=False):
    if use_browser:
        resp = requests.post(BROWSER_URL, headers=HEADERS, json={
            "url": url,
            "timeout_ms": 15000
        })
        if resp.status_code == 429:
            time.sleep(5)
            return fetch_page(url, use_browser)
        return resp.json().get("body", "")
    else:
        resp = requests.post(SINGLE_URL, headers=HEADERS, json={
            "method": "GET",
            "url": url,
            "unblocker": True
        })
        if resp.status_code == 429:
            time.sleep(5)
            return fetch_page(url, use_browser)
        return resp.json().get("data", "")
```

## Step 3: Extract Prices

```python
from bs4 import BeautifulSoup
import re

def extract_price(html, selector):
    soup = BeautifulSoup(html, "html.parser")
    element = soup.select_one(selector)
    if not element:
        return None
    # Extract numeric price from text like "$49.99" or "49,99 EUR"
    text = element.get_text(strip=True)
    match = re.search(r'[\d,.]+', text)
    return float(match.group().replace(',', '.')) if match else None
```

## Step 4: Run and Log Results

```python
import csv
from datetime import datetime

def monitor_prices():
    timestamp = datetime.now().isoformat()
    results = []

    for target in targets:
        html = fetch_page(target["url"])
        price = extract_price(html, target["selector"])
        results.append({
            "timestamp": timestamp,
            "name": target["name"],
            "url": target["url"],
            "price": price
        })
        print(f"{target['name']}: {price}")
        time.sleep(1)  # Be polite

    # Append to CSV
    with open("prices.csv", "a", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["timestamp", "name", "url", "price"])
        if f.tell() == 0:
            writer.writeheader()
        writer.writerows(results)

if __name__ == "__main__":
    monitor_prices()
```

## Step 5: Schedule It

Run the script hourly with cron:

```bash
crontab -e
# Add this line:
0 * * * * cd /path/to/project && python3 monitor.py >> monitor.log 2>&1
```

## Tips

- **Start with the single endpoint**, switch to browser if pages use JavaScript rendering
- **Add error handling**: sites change layouts. Log failures separately.
- **Keep selectors updated**: when a competitor redesigns, update the CSS selector
- **Respect the sites**: space requests, avoid peak hours, follow robots.txt

## Next Steps

- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): Pick the best approach
- [Error Handling](/docs/api/errors): Handle failures gracefully
- [Scrape a Dynamic Website](/docs/how-to/scrape-dynamic-website): Handle JavaScript-rendered pages

---

#### Reuse a Proxy Across Requests
URL: https://foura.ai/docs/how-to/reuse-a-proxy

Learn how to keep the same proxy exit across follow-up requests, so JavaScript renders, API calls, and paginated fetches all leave from the same IP.

## Why Reuse a Proxy

When you first hit a target, FourA picks a working proxy for you. Every response includes the proxy ID it used. Pass that ID back on later requests and:

- Follow-up pages land through the same exit, so session cookies and rate limits stay coherent to the target.
- A country-scoped fetch stays inside your allowlist without a fresh selection.
- The cheap `POST /api/single/` endpoint replays through a proxy you already paid to discover, at Single's cost instead of Proxy's.

The proxy ID is an opaque base36 string (something like `A1B2C3`). Never a raw IP.

## Where the ID Lives in a Response

| Endpoint | Field | When it's present |
|----------|-------|-------------------|
| `POST /api/auto/` | `session.proxy` | When `returnSession` is `true` (the default) |
| `POST /api/single/` | `proxy` (top level) | Only when the request supplied a `proxy` field |
| `POST /api/proxy/` | `proxy` (top level) | Always, on success |
| `POST /api/browser/` | `proxy` (top level) | Only when the request supplied a `proxy` field |

To grab a fresh exit without pinning one, start with Auto or Proxy. Both discover a working exit and return its ID for you.

## Pattern 1: Auto discovers, Single replays

Best when you have a target you don't know yet. Auto walks the ladder once, then Single reuses the winning session for every follow-up page.

```python
import requests

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

# Step 1: discover a working exit with Auto.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# Step 2: paginate with Single, reusing the same exit and User-Agent.
for sku in ("43", "44", "45"):
    p = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, p["status"])
```

The Auto call costs whatever its ladder spends. Every follow-up Single call costs 2 credits (Single with `unblocker`, the default).

## Pattern 2: Proxy discovers, Browser renders through the same exit

Use this when the target must see a specific exit country and the final content needs JavaScript.

```bash
# Step 1: pick a country-scoped exit with Proxy.
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "exitCountries": ["FR", "GB"],
    "request": {"method": "GET", "url": "https://example.com/pricing"}
  }'
# Response includes: "proxy": "A1B2C3", "exitCountry": "FR"

# Step 2: render the JS-heavy page through THAT exit.
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/pricing",
    "proxy": "A1B2C3",
    "timeout_ms": 20000
  }'
```

Do not call `/api/proxy/` again to refresh the selection. A new call may pick a different exit and defeat the point of pinning. If the pinned exit stops working, run a fresh `/api/proxy/` call to pick a new one, then continue with that.

## Pattern 3: Skip a burned exit

If an exit that used to work starts returning blocks or captchas, tell FourA to avoid it on the next selection.

```json
{
  "maxTries": 5,
  "ignoreProxies": ["A1B2C3"],
  "request": { "method": "GET", "url": "https://example.com/data" }
}
```

`ignoreProxies` accepts a list of proxy IDs from earlier responses. It works on `/api/proxy/` and `/api/auto/`. The list is honored on every internal retry, so a single call with `ignoreProxies` never picks the burned exits.

## How Long a Pinned Session Stays Alive

The exit itself lives as long as the underlying proxy is healthy, typically minutes to hours. If a replay starts returning challenges, blocks, or unexpected redirects, the exit was probably rotated out or the target refreshed its clearance.

Two options when that happens:

1. Fresh `/api/auto/` call for the same URL. Auto will discover a new working session; drop the previous IDs.
2. Fresh `/api/proxy/` call with `ignoreProxies: ["<burned-id>"]` if you want to keep pinning manually.

Session cookies from an Auto response also expire on the target's own schedule. Some sites bind clearance for hours; others for minutes. Treat the session as a cache, not a durable token.

## When an ID Won't Pin

Three 400s can come back from a `proxy` value, and they mean different things:

| Error | What happened | What to do |
|-------|---------------|------------|
| `Invalid proxy format` | The value isn't an ID FourA issued. A raw proxy address lands here. | Send the opaque string from a response, verbatim. |
| `Proxy not found` | The ID decoded, but it no longer resolves to a live exit. | Take a fresh exit from a new Auto or Proxy call. |
| `Managed exit: this proxy id cannot be pinned to a request` | The exit is real, but it isn't one FourA will hold open for a named request. | Don't pin it. Keep using the session it came back on, or run the call through `POST /api/proxy/` and take whichever exit it picks. |

The third one comes back from an ID a successful call handed you, so you can hit it without having done anything wrong. Treat it the way you'd treat an expired session: fall back to a fresh discovery call rather than retrying the same ID.

## Common Mistakes

- **Reusing a proxy ID across accounts.** Proxy IDs are per-response identifiers. Passing an ID from one API key into another isn't guaranteed to resolve to the same exit.
- **Trying to decode the ID.** The base36 string is opaque. Don't parse it, don't strip characters, don't lowercase it. Pass it back verbatim.
- **Pinning through a rate-limited exit.** If the target rate-limits per IP, funneling many requests through one exit will trigger blocks faster. For high-volume workloads, let Auto or Proxy rotate through many exits and pin only where the target genuinely requires it.
- **Ignoring `exitCountries` on the follow-up.** If you pin a scoped exit and then call Proxy again without `exitCountries`, the follow-up may land through a different country. Keep the scope on every call that needs it.

## Related

- [API Endpoints](/docs/api/endpoints): Full parameter and response reference
- [Smart Fetch (Auto)](/docs/guides/smart-fetch): How Auto builds the session you replay
- [Handling Anti-Bot Protection](/docs/guides/anti-bot-protection): When pinning helps and when rotation is better
- [Common Issues](/docs/troubleshooting/common-issues): `no_eligible_proxy` and other proxy errors
- [Why a Proxy Request Ran Out of Tries](/docs/troubleshooting/proxy-attempt-report): Reading `attemptReport` when a Proxy call gives up

---

#### Run Requests in Parallel
URL: https://foura.ai/docs/how-to/run-requests-in-parallel

## What You'll Learn

How to run a large batch of FourA requests concurrently without collecting 429s, by capping how many calls you keep open and by reacting to a refusal instead of repeating it.

## Prerequisites

- A FourA API key ([get one here](/docs/getting-started/authentication))
- Python 3.9+ with `requests`, or Node.js 18+

## The Limits You're Working Against

Your plan carries two ceilings per endpoint: how many requests may run at the same time, and how many may start per minute (Browser has a per-day allowance instead of a per-minute one). Single, Proxy and Browser each have their own numbers, and the **Limits & Features** tab of [Usage & Limits](/docs/dashboard/quota) lists them.

The request that goes over the concurrency ceiling comes back as HTTP 429 with `X-FourA-Limit: plan_limit_concurrency` and the ceiling in the body:

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous single request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

The one that goes over the per-minute ceiling comes back with `X-FourA-Limit: plan_limit_rate` and `retry_after_seconds` running to the end of the minute.

Both refusals are immediate. FourA doesn't queue the call and hand it back later, so nothing is spent and nothing is billed. Refused calls do count toward the sliding minute, though, so a retry storm extends its own cooldown. Full field reference: [Rate Limits](/docs/api/rate-limits).

Two things count that people often miss:

- A `POST /api/auto/` call isn't counted by itself, but every Single, Proxy and Browser sub-call it makes for you is. One auto call can hold more than one slot while its ladder runs.
- A Browser request occupies its slot for as long as the page takes to render, which is far longer than a Single request. A batch of browser calls fills its ceiling with fewer requests than a batch of single calls.

## Step 1: Cap Your Own Concurrency

Pick a number below the ceiling for the endpoint you're calling and hold it. A worker pool does this in one line:

```python
import os
import concurrent.futures
import requests

API = "https://eu.api.foura.ai/api/single/"
KEY = os.environ["FOURA_API_KEY"]
HEADERS = {"X-API-Key": KEY, "Content-Type": "application/json"}

# Below your plan's Single concurrency, so a slow request never pushes the batch over it.
MAX_IN_FLIGHT = 30

def fetch_one(url):
    resp = requests.post(API, headers=HEADERS, json={"method": "GET", "url": url}, timeout=60)
    return url, resp.status_code, resp.json()

def fetch_all(urls):
    results = []
    with concurrent.futures.ThreadPoolExecutor(max_workers=MAX_IN_FLIGHT) as pool:
        for outcome in concurrent.futures.as_completed(pool.submit(fetch_one, u) for u in urls):
            results.append(outcome.result())
    return results
```

`max_workers` is the whole mechanism. The pool never has more than that many calls open, so the batch can be a million URLs long and still stay under the limit.

Leave headroom. If two processes on your side share one API key, they share one ceiling, so give each of them half. If a fast target lets the pool finish requests quicker than a minute allows, pace the workers to stay under the per-minute ceiling too.

## Step 2: Back Off Instead of Re-Sending

If a refusal does arrive, the wrong answer is to re-send the batch at once. Every call in it gets refused again, and the retries pile on top of the requests that were already running.

Wait first. The wait is in the `Retry-After` header and in `retry_after_seconds` in the body:

```python
import time

# Plan limits that no short wait will clear.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth", "plan_limit_feature", "plan_limit_premium"}

def fetch_one(url, attempts=4):
    for attempt in range(attempts):
        resp = requests.post(API, headers=HEADERS, json={"method": "GET", "url": url}, timeout=60)

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"stopped by {limit}")

        if resp.status_code not in (429, 503):
            return url, resp.status_code, resp.json()

        header = resp.headers.get("Retry-After")
        if header and header.isdigit():
            wait = int(header)
        else:
            body = resp.json()
            wait = body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        time.sleep(wait)

    return url, 429, {"error": "still refused after retries"}
```

Add jitter when you're running many workers. Without it, every worker refused in the same second wakes up in the same second and refuses together.

```python
import random
time.sleep(wait + random.uniform(0, 0.5))
```

## Step 3: The Same Thing in Node

```javascript
const API = 'https://eu.api.foura.ai/api/single/';
const HEADERS = {
  'X-API-Key': process.env.FOURA_API_KEY,
  'Content-Type': 'application/json',
};
const MAX_IN_FLIGHT = 30;

async function fetchOne(url) {
  const resp = await fetch(API, {
    method: 'POST',
    headers: HEADERS,
    body: JSON.stringify({ method: 'GET', url }),
  });
  return { url, status: resp.status, body: await resp.json() };
}

async function fetchAll(urls) {
  const queue = [...urls];
  const results = [];

  async function worker() {
    while (queue.length) {
      results.push(await fetchOne(queue.pop()));
    }
  }

  await Promise.all(
    Array.from({ length: Math.min(MAX_IN_FLIGHT, urls.length) }, worker)
  );
  return results;
}
```

A fixed number of workers pulling from one queue keeps exactly that many calls open, whatever the batch size.

## Step 4: Watch What You're Actually Using

Open **Usage & Limits** in the [dashboard](https://foura.ai/dashboard). The live counters next to your caps show concurrency, per-minute rate, and browser requests per day as they move, so you can size `MAX_IN_FLIGHT` against a real run rather than a guess.

The [Activity Log](/docs/dashboard/activity-log) records refusals too. A run that finished with the right number of rows but a scatter of `rate_limit` outcomes was throttling itself.

## Common Mistakes

- **Firing the whole list at once.** `asyncio.gather` over 5,000 URLs, or `Promise.all` over an unbounded array, opens 5,000 calls. Bound the pool, not the list.
- **Retrying in parallel.** Re-sending every refused call the moment it's refused reproduces the burst that caused the refusal. Wait the `Retry-After`, and add jitter.
- **Treating a daily or period allowance as a wait.** `plan_limit_browser_daily` clears at midnight UTC, `plan_limit_credits` and `plan_limit_bandwidth` at the end of the billing period. Stop the run and read `resets_at` from the body where there is one.
- **Counting auto calls as one slot each.** The ladder inside `/api/auto/` makes real sub-calls, and those are what the ceilings count.
- **Sharing a key across processes without dividing the budget.** The ceilings are per account, not per process.
- **Sizing one pool for every endpoint.** Single, Proxy and Browser each have their own concurrency number. A pool sized for Single overshoots a smaller Browser ceiling.

## Related

- [Rate Limits](/docs/api/rate-limits): Every refusal shape and what each field means
- [Response Headers](/docs/api/response-headers): `X-FourA-Limit` and `Retry-After`
- [Request Outcomes](/docs/api/outcomes): Why a `rate_limit` outcome is never billed
- [Usage & Limits](/docs/dashboard/quota): Where the live counters and your plan's numbers are
- [Smart Fetch (Auto)](/docs/guides/smart-fetch): How one auto call turns into several sub-calls

---

### Mcp

#### MCP Server
URL: https://foura.ai/docs/mcp/server

# MCP Server

Use FourA from any [Model Context Protocol](https://modelcontextprotocol.io) client (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) as four native tools and six workflow prompts. No integration code, no custom HTTP client.

Open source on [GitHub](https://github.com/fouradata/mcp); on [npm](https://www.npmjs.com/package/@fouradata/mcp) as `@fouradata/mcp`. Current release: `0.5.0`.

## Quick Start: local stdio (recommended for Claude Desktop)

Grab a key at [foura.ai/dashboard#api-keys](https://foura.ai/dashboard#api-keys) (one click, shown once on creation, format `pk_live_...`). Drop this into your MCP client's config:

```json
{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": { "FOURA_API_KEY": "pk_live_..." }
    }
  }
}
```

> **Claude Desktop gotcha:** fully quit Claude Desktop (`Cmd+Q` on macOS) **before** editing the config file. If the app is still running, it will overwrite your edits with its in-memory config on exit.

The `npx` command downloads `@fouradata/mcp` on first launch and runs it as a subprocess of your MCP client. No global install needed.

| Client | Where the config lives |
|---|---|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | `claude mcp add foura -- npx -y @fouradata/mcp` (set `FOURA_API_KEY` in env first) |
| Cursor | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code (MCP extension) | `.vscode/mcp.json` |

Restart the client. The tools (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) and six prompts appear in your tool list.

## Quick Start: hosted (Streamable HTTP)

For clients that support the Streamable HTTP transport (Cursor, Windsurf, VS Code, Claude Code with `--transport http`), point them at the hosted endpoint instead of running a local subprocess:

```json
{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}
```

For Claude Desktop, use the stdio config above or bridge the hosted endpoint through `mcp-remote`:

```json
{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}
```

## Hosted endpoint reference

| Property | Value |
|---|---|
| URL | `https://mcp.foura.ai/mcp` |
| Transport | Streamable HTTP (POST `/mcp`, SSE responses) |
| Authentication | `Authorization: Bearer pk_live_...` per request |
| MCP-Protocol-Version | Per `@modelcontextprotocol/sdk` (currently `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`) |
| 401 challenge | `WWW-Authenticate: Bearer realm="foura-mcp"` |

The 401 challenge carries no RFC 9728 `resource_metadata` parameter, on purpose. Advertising one makes an OAuth-capable client start a flow this server doesn't implement. Send your `pk_live_` key as a Bearer token and the 401 goes away.

The hosted server is stateless. Every request brings its own key, which the server forwards to the FourA API as `X-API-Key`. One key opens all four tools.

For protection against DNS-rebinding (CVE-2025-66414), the server validates the `Host` header (must be `mcp.foura.ai` or localhost) and the `Origin` header when present (allowlisted: `mcp.foura.ai`, `claude.ai`, `app.cursor.sh`, `app.cursor.com`). Server-to-server callers (`curl`, MCP clients in stdio bridge mode) send no `Origin` and pass through.

## Tools

All four tools are annotated `readOnlyHint: true` and `openWorldHint: true` per the [MCP 2025-06-18 spec](https://modelcontextprotocol.io/specification/2025-06-18/server/tools). Clients that auto-approve trusted read-only tools call them without a per-request confirmation modal.

`foura_auto` is the smart default: give it a URL and it returns the content, picking the fetch method for you. The other three are the lower-level primitives it orchestrates; reach for them when you want explicit control.

### foura_auto

Give it a URL when you want FourA to choose the request method. It makes bounded attempts across the available HTTP, proxy, and browser paths. Pass `validate` on protected targets so the response must contain content that identifies the real page. If no attempt satisfies the validation, the tool returns an error instead of presenting a challenge page as success.

The response includes completion details in `meta` and, by default, a reusable `session` with `proxy`, `cookies`, and `userAgent`. For a plain follow-up, call `foura_single` with `session.proxy` as `proxy`, serialize the cookies as a `Cookie` header, and send `session.userAgent` as the `User-Agent` header. For JavaScript rendering, pass the session values to the matching `foura_browser` fields.

### foura_single

One HTTP request, response back. Mirrors [`POST /api/single/`](/docs/api/endpoints) one-to-one.

Use for static pages, JSON APIs, server-rendered HTML.

#### Choosing which browser you present

A request presents the latest Google Chrome by default. When a target accepts one browser and refuses another, set `browser` (Chrome, Edge, Safari, Firefox, or Tor), `os` (Windows, macOS, Android, or iOS), or `version`, or pass an exact `profile` id:

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

The newest version wins when several profiles match. A combination that does not exist returns an error listing what is available, so a request is never sent as a browser you did not choose. Selection needs `unblocker`, which is on by default. The catalogue is published at [`GET /api/profiles`](/docs/api/endpoints) and needs no API key.

The same four fields sit inside `foura_proxy`'s `request` object.

### foura_proxy

Route one HTTP request through rotating proxies with automatic retry. Use it when `foura_single` is blocked or the target requires a specific exit country.

Set `exitCountries` to a strict allowlist of two-letter target-visible country codes supplied by the user or target requirements:

```json
{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}
```

Values are trimmed, uppercased, and deduplicated. Proxies with unknown exits are excluded, and the request never falls back to an unrequested country. Selection uses the latest available target-visible country metadata, normally updated within ten minutes; it is not a live geolocation lookup during the request. Do not infer the serving country from the proxy host address.

A scoped success returns `exitCountry` and the reusable `proxy` ID. Check that `exitCountry` belongs to the requested allowlist. If the current pool has no match, the tool returns `code: "no_eligible_proxy"` with the normalized scope in `details.exitCountries`. Preserve that scope and retry later. Change or widen it only when the user explicitly changes the requirement.

If the selected page later needs JavaScript, pass the returned `proxy` ID to `foura_browser.proxy` so the browser reuses the same exit.

### foura_browser

Full browser session. JavaScript runs, the DOM renders, cookies come back. Mirrors [`POST /api/browser/`](/docs/api/endpoints).

Use for single-page apps, lazy-loaded content, or pages behind anti-bot challenges that need a real browser to clear.

For input shapes, defaults, and validation rules on each tool, refer to the [REST endpoint reference](/docs/api/endpoints). Tool schemas match the REST API field-for-field, plus the MCP-only `offload_large` opt-in (see below).

### When a target runs a bot check

`foura_single` and `foura_proxy` return `defense` when the target ran a bot check on the way to the body. `defense.solved: true` means the check was met and `data` is the real page; `false` means the body may be a challenge page. Retry with a different browser, os, or version, or move up to `foura_proxy` or `foura_browser`, instead of treating the challenge page as content.

## Typed responses

Every tool response includes both `content` (human-readable text summary) and `structuredContent` (typed JSON validated against the tool's `outputSchema`). Each tool has its own unique shape:

- `foura_auto`: single-shaped `{ status, headers, data }` plus `meta` (`{ rung, solved, attempts, credits }`, always present, where `rung` is one of `cache`, `probe`, `proxy`, `browser`, `fail`) and, by default, `session` (`{ proxy, cookies, userAgent }`) for replay through the lower-level tools. No `total_time`.
- `foura_single`: `{ status, headers, data, total_time, ... }` (headers is an array, one entry per redirect hop)
- `foura_proxy`: same as single plus `{ proxy, total }`; a scoped success also includes `exitCountry`
- `foura_browser`: distinct shape `{ status, headers: object, body, cookies, userAgent }` (note: `body` may be a string or object depending on content-type)

Clients that support `structuredContent` can pass the typed object directly to the LLM instead of requiring it to parse JSON from prose.

### Multi-value response headers

Headers that appear multiple times (`Set-Cookie`, `Link`, `WWW-Authenticate`) come back as arrays:

```json
{
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html",
      "set-cookie": ["a=1; Path=/", "b=2; Path=/"]
    }
  ]
}
```

This matters for sites that set session + tracking + consent cookies in one response (most of e-commerce).

## Large responses: `offload_large` (default: inline)

By default (since v0.2.0), full response bodies are returned inline in `structuredContent` regardless of size. This works in every MCP client out of the box.

If your client supports MCP `resources/read` AND you want token savings on big pages, pass `offload_large: true` per tool call. Responses >= 50 KB are then written to disk, returned as a `resource_link`, and your client fetches the body only when it actually needs it. Cached payloads expire after 1 hour.

```json
{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
```

| Client | `offload_large: true` |
|---|---|
| Claude Desktop | not yet, leave default `false` |
| Claude Code, Cursor, Windsurf | supported |
| VS Code MCP extension | supported |

Tenant-isolated: each API key gets its own namespace (`sha256(apiKey)[:16]`). Only the key that stored a payload can read it back. Cross-tenant reads return `Payload not found` with no existence leak.

## Built-in Prompts

Six workflow templates surface under `/prompts` in any MCP client. Each takes named arguments and returns a templated user message orchestrating one or more tools.

| Prompt | Arguments | What it does |
|---|---|---|
| `smart_fetch` | `url`, optional `must_contain`, `extract` | Auto fetch (picks the method, handles bot protection), then return or extract the content |
| `scrape_product_page` | `url` | Browser fetch, then extract product title, price, image, stock, SKU as JSON |
| `extract_article` | `url` | Single with proxy fallback, then strip nav/ads and return clean article JSON |
| `monitor_pricing` | `url`, optional `target_price` | Proxy fetch, extract current price, compare to target |
| `check_endpoint_health` | `url`, optional `expected_text` | Single with strict validation, return reachability and timing |
| `bulk_fetch_urls` | `urls` (comma-separated) | Parallel single, auto-fallback to proxy per URL, return metadata only |

Prompts cost zero tokens at idle. Only invoked prompts enter the LLM context.

Full text plus manual fallback prompts: [MCP Recipes](/docs/mcp/recipes).

## Error envelope

Every error (`isError: true`) carries a `structuredContent` envelope. Minimum fields on every error:

```json
{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}
```

On upstream errors with HTTP status, `status` is also present. On rate-limit and capacity errors, the upstream envelope adds `retryAfter`, `current.{concurrency, rpm}`, and `limits.{maxConcurrency, maxRpm}`. See [API Errors](/docs/api/errors) for the underlying REST shape.

Stable `code` values:

| Code | HTTP | Meaning | Retry safe? |
|---|---|---|---|
| `ssrf_blocked` | n/a | Target IP in a private or reserved range (RFC 5735, 6598, IPv6 reserved) | No, change URL |
| `upstream_non_json` | varies | Upstream returned malformed body | Maybe, investigate |
| `output_validation_failed` | n/a | The MCP server's `outputSchema` rejected the upstream response (server bug or unexpected upstream shape) | Maybe, report |
| `bad_request` | 400 | Input shape rejected | No, fix arguments |
| `auth_failed` | 401 | Key missing, invalid, or deactivated | No, fix the key |
| `forbidden` | 403 | Authenticated but not allowed | No, or switch to `foura_proxy` |
| `not_found` | 404 | Target or endpoint missing | No |
| `rate_limited` | 429 | RPM cap hit | Yes, wait `retryAfter` |
| `at_capacity` | 503 | Concurrency cap hit | Yes, wait `retryAfter` |
| `service_disabled` | 503 | Maintenance window or your plan doesn't include this tool | Contact support |
| `service_unavailable` | 503 | Generic 503 | Yes, short backoff |
| `upstream_error` | 500+ | Upstream 5xx | Yes, exponential backoff |
| `upstream_client_error` | 4xx | Other 4xx | Usually no |
| `upstream_unknown` | other | Defensive, should not occur in practice | Investigate |
| `no_eligible_proxy` | n/a | No proxy matches the strict `exitCountries` scope | Retry later; change scope only explicitly |

LLM agents can read `code` directly for retry logic without parsing prose. Authentication walkthrough: [Authentication](/docs/getting-started/authentication).

## Limits

- Inline body by default. With `offload_large: true`, responses >= 50 KB go to disk + `resource_link` (per-tenant, 1-hour TTL).
- Private targets are refused (RFC 5735, RFC 6598, IPv6 reserved blocks) at the MCP layer. Only public hosts forwarded.
- Request body cap of 256 KB on incoming `/mcp` requests (real MCP payloads are < 4 KB).
- Rate limits are enforced by the FourA API per service. See [Rate Limits](/docs/api/rate-limits).

## Self-Hosting

The full server source is public on [GitHub](https://github.com/fouradata/mcp) under `@fouradata/mcp`. Clone the repo, `npm install`, `npm run build`, and run `node dist/http.js` to stand up your own instance. Runs stateless in a single container behind any load balancer.

Configurable environment:

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `3076` | HTTP listen port |
| `FOURA_API_BASE` | `https://api.foura.ai/api` | Upstream FourA REST base URL |
| `FOURA_MCP_PAYLOADS_DIR` | `/data/payloads` | Where >= 50 KB responses are cached on disk (with `offload_large: true`) |
| `FOURA_MCP_ALLOWED_HOSTS` | `mcp.foura.ai,localhost,127.0.0.1,[::1]` | Hostname allowlist for `Host` header (DNS-rebinding defense) |
| `FOURA_MCP_ALLOWED_ORIGINS` | `https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com` | Origin allowlist for browser callers |
| `FOURA_MCP_RESOURCE_METADATA_URL` | `https://foura.ai/docs/mcp/server#auth` | URL returned in `WWW-Authenticate` on 401 |

The official container runs as `uid 1001` (non-root). The `/data/payloads` host bind mount must be writable by that uid.

Scale horizontally behind any load balancer. Clients supply their key on every request, so there's no sticky session.

---

#### MCP Server Errors
URL: https://foura.ai/docs/mcp/errors

# MCP Server Errors

How to handle errors returned by the [foura-mcp server](/docs/mcp/server).

Every error response from any of the four tools (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) is structured. LLM agents can read the `code` field for retry logic without parsing prose.

## Envelope shape

Every error (`isError: true`) carries a `structuredContent` block. Minimum fields on every error:

```json
{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}
```

On upstream errors with HTTP status, `status` is also present. When the platform's shared allowance refuses a call, the envelope adds `retryAfter`, `current.{concurrency, rpm}`, and `limits.{maxConcurrency, maxRpm}`, same shape as the underlying [REST API errors](/docs/api/errors).

When one of your own account's limits refuses it, the upstream body carries `reason` and `retry_after_seconds` instead, so `retryAfter`, `current` and `limits` are all absent. Treat a `rate_limited` without `retryAfter` as your own ceiling and back off on your own schedule.

## Stable `code` values

| Code | HTTP | Meaning | Retry safe? |
|---|---|---|---|
| `ssrf_blocked` | n/a | Target IP in a private or reserved range (RFC 5735, RFC 6598, IPv6 reserved) | No, change the URL |
| `upstream_non_json` | varies | Upstream returned a body that wasn't valid JSON | Maybe, investigate |
| `output_validation_failed` | n/a | The MCP server's `outputSchema` rejected the upstream response (server bug or unexpected upstream shape) | Maybe, report |
| `bad_request` | 400 | Input shape rejected by the FourA API | No, fix the arguments |
| `auth_failed` | 401 | The FourA API key is missing, invalid, or deactivated; this is not about target-site credentials | No, fix the FourA key |
| `forbidden` | 403 | Target rejected the request (anti-bot, geo-block) | No, or switch to `foura_proxy` |
| `not_found` | 404 | Target URL or endpoint doesn't exist | No |
| `rate_limited` | 429 | Either your account's own ceiling (too many calls at once, or a spent daily Browser allowance) or the platform's shared per-minute allowance | Yes, wait `retryAfter` when it's there, otherwise back off |
| `at_capacity` | 503 | Concurrency cap hit (`current.concurrency` > `limits.maxConcurrency`) | Yes, wait `retryAfter` seconds |
| `service_disabled` | 503 | Service disabled for your account (plan or maintenance) | Contact support |
| `service_unavailable` | 503 | Generic 503 from upstream | Yes, short backoff |
| `upstream_error` | 500+ | Upstream 5xx | Yes, exponential backoff |
| `upstream_client_error` | 4xx | Other 4xx not covered above | Usually no |
| `upstream_unknown` | other | Defensive, should not occur in practice | Investigate |
| `no_eligible_proxy` | n/a | No proxy matches the strict `exitCountries` allowlist; `details.exitCountries` contains the normalized scope | Retry later; change scope only explicitly |

## HTTP-level errors from the MCP server

Some failures happen at the MCP transport layer, before any tool is called. These return raw JSON-RPC errors (no `structuredContent`):

| HTTP | When | What you see |
|---|---|---|
| 400 | Unsupported `MCP-Protocol-Version` header | `Unsupported MCP-Protocol-Version: <value>. Supported: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07.` |
| 401 | Missing or malformed `Authorization` header | JSON-RPC error + `WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"` |
| 403 | Disallowed `Origin` or `Host` header (DNS-rebinding defense, CVE-2025-66414) | `Origin <value> is not in the allowlist` or `Host <value> is not in the allowlist` |
| 405 | `GET` or `DELETE` on `/mcp` (stateless mode) | `Method not allowed in stateless mode. Use POST /mcp.` |
| 413 | Request body > 256 KB | Express default 413 |

The allowlists for 403 are env-configurable for self-hosters via `FOURA_MCP_ALLOWED_HOSTS` and `FOURA_MCP_ALLOWED_ORIGINS`.

## Refused browser profiles

A browser profile that the catalogue cannot present, or a profile sent with `unblocker` set to `false`, comes back as an upstream failure with the reason in `error` and the request never leaves FourA. The message names what is available, so retry with one of the listed combinations rather than the same one.

These are refusals, not outages: retrying the identical request cannot succeed, and no other browser was used in its place.

## Retry strategy

Four buckets:

- **Wait and retry**: `rate_limited`, `at_capacity`, `service_unavailable`, `upstream_error`. Honour `retryAfter` when present. Use exponential backoff with jitter when it isn't there, which is what a `rate_limited` from your account's own ceiling looks like. Don't answer it by re-issuing every queued tool call at once: cut how many you run in parallel instead.
- **Preserve scope and retry later**: `no_eligible_proxy`. Do not remove `exitCountries` or substitute another country silently. Change or widen the allowlist only when the user explicitly changes the requirement.
- **Do not retry until the input or credential is fixed**: `bad_request`, `auth_failed`, `not_found`, `ssrf_blocked`. For `auth_failed`, verify the FourA API key, not target-site credentials.
- **Switch tool when the content requires it**: `forbidden` on `foura_single` can justify a bounded `foura_proxy` attempt. Use `foura_browser` when the desired content needs JavaScript. After a successful proxy selection, pass the returned `proxy` ID into `foura_browser.proxy` instead of starting a new selection.

## Retry example (TypeScript, MCP-side)

```typescript
async function callWithRetry(call: () => Promise<any>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await call();
    if (!r.isError) return r;

    const code = r.structuredContent?.code;
    const wait = r.structuredContent?.retryAfter ?? Math.min(2 ** attempt, 30);

    if (["rate_limited", "at_capacity", "service_unavailable", "upstream_error"].includes(code)) {
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    // Non-retryable, surface to caller
    throw new Error(`${code}: ${r.structuredContent?.error}`);
  }
  throw new Error("max retries exceeded");
}
```

## Related

- [MCP Server](/docs/mcp/server), the four tools and their schemas
- [MCP Recipes](/docs/mcp/recipes), workflow prompts shipped with the server
- [API Errors](/docs/api/errors), same envelope at the underlying REST API layer
- [Rate Limits](/docs/api/rate-limits), the account and platform limits behind `rate_limited` and `at_capacity`

---

#### MCP Recipes
URL: https://foura.ai/docs/mcp/recipes

# MCP Recipes

Six ready-to-paste prompts you can run inside any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) after installing the [FourA MCP server](/docs/mcp/server).

Each recipe uses `foura_auto` (the smart default) or one or more of the lower-level `foura_single`, `foura_proxy`, `foura_browser` for a common scraping job. Two ways to use them:

1. **Invoke the built-in prompt** - every MCP client surfaces server-provided prompts as a slash command or `/prompts` panel. Pick the prompt, fill in the arguments, run. The MCP server returns the templated workflow; the LLM executes it with the right tools.
2. **Copy the prose** below into your own chat. Same effect, less discoverable.

The MCP server ships these as native prompts: `smart_fetch`, `scrape_product_page`, `extract_article`, `monitor_pricing`, `check_endpoint_health`, `bulk_fetch_urls`.

> **Note on large pages (v0.2.0+):** by default, response bodies come back inline in `structuredContent` regardless of size - this works in every MCP client including Claude Desktop. If you're on a client that supports MCP `resources/read` AND you want token savings on big pages, pass `offload_large: true` in the tool call. Responses >= 50 KB then come as a `resource_link` your client fetches on demand. The built-in prompts below assume the default (inline).


Open source on [GitHub](https://github.com/fouradata/mcp); on [npm](https://www.npmjs.com/package/@fouradata/mcp) as `@fouradata/mcp`.

## Smart fetch (auto): start here

The simplest recipe: hand a URL to `foura_auto` and let it make bounded attempts across the available request methods. Use it whenever you want the content and do not need to choose the first tool yourself.

Built-in: `smart_fetch(url, must_contain?, extract?)`

Manual prompt:

```
Fetch <URL> using foura_auto.

Pass validate.data.accept:["<a string the real page must contain>"] so only the real page counts as success. Auto makes bounded attempts and returns an error if none satisfies the validation.

For a plain follow-up, call foura_single with session.proxy as proxy, session.cookies serialized as a Cookie header, and session.userAgent as a User-Agent header. For JavaScript, pass the session values to the matching foura_browser fields.

Return the content, or extract the requested fields as JSON.
```

When this is the right recipe: a first attempt where FourA should choose the method, especially when content validation can distinguish a real page from a block page.

## 1. Scrape a product page

For e-commerce product detail pages, including single-page-app sites and pages behind anti-bot challenges.

Built-in: `scrape_product_page(url)`

Manual prompt:

```
Fetch the product page at <URL> using foura_browser - most product pages are single-page apps and need JavaScript to render.

From the response body extract:
- product title
- price (with currency)
- primary product image URL (absolute, not relative)
- availability / stock status
- product SKU or ID if visible

Return as JSON: {"title": "...", "price": 0, "currency": "USD", "image_url": "...", "in_stock": true, "sku": "..."}
```

When this is the right recipe: a price comparison agent, a back-in-stock notifier, a competitive analysis spreadsheet.

## 2. Extract an article

For news articles, blog posts, technical documentation, anything where you want clean reading text without nav, ads, and footer noise.

Built-in: `extract_article(url)`

Manual prompt:

```
Fetch <URL> using foura_single with unblocker:true. Use plain HTTP first when the article is present in the server-rendered response.

If foura_single returns a 403, captcha page, or empty content, retry the same URL with foura_proxy (maxTries:3) - it routes through a rotating proxy pool.

From the response, extract:
- headline (the main H1, not the page title bar)
- author byline (may be inside .author, [rel=author], itemprop)
- publication date (look for <time>, .published, or JSON-LD)
- main article body (strip navigation, ads, related-content, footer, comments)
- canonical URL (rel=canonical or og:url)

Return as JSON: {"title": "...", "author": "...", "date_published": "ISO8601", "body": "...", "canonical_url": "..."}
```

When this is the right recipe: a research summarizer, an RSS-of-one-site, a daily news digest.

## 3. Monitor a price

For pricing pages and product offers, with optional comparison against a target price.

Built-in: `monitor_pricing(url, target_price?)`

Manual prompt:

```
Use foura_proxy with maxTries:5 and unblocker:true to fetch <URL>. Pricing pages often have aggressive bot detection, so go through the proxy pool from the start.

Extract the current price (look for visible $/€/£ amounts, JSON-LD Offer schema, [itemprop=price]).

If a target price is provided, compare: report whether current is below/at/above target and the absolute difference.

Return as JSON: {"url": "...", "current_price": 0.00, "currency": "USD", "target_price": 0, "difference": 0, "status": "below|at|above"}
```

When this is the right recipe: a savings-alert agent, a travel-fare watcher, a B2B competitor pricing tracker.

## 4. Check endpoint health

For uptime probes and API endpoint validation.

Built-in: `check_endpoint_health(url, expected_text?)`

Manual prompt:

```
Use foura_single with GET on <URL>, timeout_ms:5000, and validate.status.accept:[200]. If an expected substring is provided, also set validate.data.accept:["<EXPECTED>"] so the request only counts as success when the body contains it.

Report:
- reachable (true if any response came back, false on connection error/timeout)
- status_code (HTTP code from target)
- total_time_ms (from the total_time field)
- validation_passed (true if status + body validation conditions were met)

Return as JSON: {"url": "...", "reachable": true, "status_code": 200, "total_time_ms": 0, "validation_passed": true}
```

When this is the right recipe: an external uptime monitor, a deploy smoke test, a third-party API watchdog.

## 5. Fetch a list of URLs in parallel

For batch jobs where you want metadata about many URLs without inlining their bodies.

Built-in: `bulk_fetch_urls(urls)`

Manual prompt:

```
Parse the following comma-separated URLs and fetch each one concurrently using foura_single (unblocker:true).

URLs: <COMMA_SEPARATED>

For any URL that returns 403, captcha page, or empty body - retry that single URL with foura_proxy (maxTries:3).

Return a JSON array, one entry per URL in input order:
[{"url": "...", "status": 200, "success": true, "body_size_bytes": 0, "via": "single|proxy", "error": null}, ...]

Do NOT inline full response bodies in the output - only metadata. If you need body content, call foura_single individually after this report.
```

When this is the right recipe: a sitemap reachability sweep, a link-rot audit, a "which of these 50 product URLs still exist" check.

## 6. Choose and reuse a country-scoped exit

Use this when the target must see the request from one of a specific set of countries, including JavaScript pages where proxy selection must happen before browser rendering.

Manual prompt:

```
First call foura_proxy for the actual target:
{
  "maxTries": 5,
  "exitCountries": ["FR", "GB"],
  "request": { "method": "GET", "url": "<TARGET_URL>" }
}

Treat exitCountries as a strict allowlist. On success, verify that exitCountry is FR or GB and capture the returned proxy ID.

If the page then needs JavaScript, call foura_browser with the returned proxy ID in foura_browser.proxy. Do not start a new proxy selection, because that may choose a different exit.

If foura_proxy returns no_eligible_proxy, preserve the requested country scope and retry later. Change or widen the list only after the user explicitly changes the requirement. Never retry silently without exitCountries.
```

When this is the right recipe: regional content, licensed markets, geo-specific pricing, or any workflow that needs a verified target-visible country and then reuses the selected exit.

## 7. Protected page: proxy first, browser when JavaScript is needed

Use a bounded proxy attempt with content validation when a direct request returns a block page. If the validated response succeeds but the desired content still needs JavaScript, reuse that exact proxy ID in the browser. A visible protection vendor is not a guarantee that any method will succeed.

Manual prompt:

```
Step 1 - call foura_proxy for <TARGET_URL>. Put a string unique to the real page in request.validate.data.accept. If the user supplied an allowed country list, pass it as exitCountries; do not guess country codes.

Step 2 - if the response passes validation and JavaScript is still required, call foura_browser with the returned proxy ID in the proxy field.

Do not call foura_proxy again after a successful selection, because the new call may choose a different exit. If the bounded attempt fails, report the failure honestly instead of claiming support for the target's protection vendor.
```

When this is the right recipe: a protected target where HTTP can select a working exit but the final content requires JavaScript rendering.

## 8. Blocked on a static page: change the browser you present

Use this when a static target returns a block or challenge page and JavaScript is not the problem. The request presents the latest Google Chrome by default; some targets accept a different browser or platform.

Manual prompt:

```
Step 1 - call foura_single for <TARGET_URL> with request validation: put a string unique to the real page in validate.data.accept.

Step 2 - if the response is a block page, or defense comes back with solved false, call foura_single again with a different presented browser, for example {"browser": "Firefox"} or {"browser": "Chrome", "os": "Android"}. Keep the same validation.

If the tool answers that the combination does not exist, pick one from the list it returns. Do not retry the same impossible combination, and do not assume another browser was used instead: the request was refused, not substituted.

Step 3 - if changing the presented browser does not help, escalate to foura_proxy for a different exit, and to foura_browser only when the content genuinely needs JavaScript.
```

When this is the right recipe: a server-rendered target that filters on the client it sees rather than on the exit address. Changing the presented browser costs nothing extra and is worth trying before proxy rotation.

## Tips that apply to all of them

- **Not sure which tool? Use foura_auto.** It picks the method and handles escalation for you. Reach for a specific tool only when you want explicit control.
- **Start with `foura_single` when plain HTTP is enough.** Escalate to `foura_proxy` when the direct request is blocked and to `foura_browser` when the desired content needs JavaScript.
- **Browser-like request headers are on by default (`unblocker`).** Keep content validation in place so a block page does not count as success, and change the presented browser with `browser`, `os`, or `version` when a target refuses the default.
- **Validation rules save retries.** Set `validate.data.fail:["captcha", "blocked"]` so an obviously-blocked response counts as failure and triggers retry/proxy escalation, rather than being parsed as success.
- **Country scope is strict.** A `no_eligible_proxy` result is not permission to retry without `exitCountries`; preserve the requirement or ask the user before changing it.
- **Large bodies are inline by default (v0.2.0+).** Pass `offload_large: true` to switch to `resource_link` + `resources/read` on clients that support those capabilities.

## Want a recipe that isn't here?

Email `support@foura.ai` with the use case. The MCP server ships new prompts at the same cadence as REST API releases.

---

### Troubleshooting

#### Common Issues
URL: https://foura.ai/docs/troubleshooting/common-issues

Solutions to the most common problems when using the FourA API.

## Empty or Incomplete Content

**Symptom:** The API returns a 200 status but the `data` field is empty or missing expected content.

**Cause:** The target page uses JavaScript to render content after the initial page load.

**Solution:** Switch from the single endpoint to the browser endpoint. Use `checkText` to verify the content loaded:

```bash
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/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Note: the browser endpoint returns content in the `body` field (not `data`).

## 403 Forbidden or Captcha Pages

**Symptom:** The API returns HTML containing a captcha challenge or an access denied page.

**Cause:** The target site detected the request as automated and blocked it.

**Solution:** Use the proxy endpoint for automatic IP rotation:

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'
```

If the issue persists, increase `maxTries` to give the proxy rotation more attempts.

A 403 that the target returned arrives as HTTP 200 with `status: 403` inside the body. A 403 on the call itself, with an `X-FourA-Limit` header, is a different thing: see [403 Not in Your Plan](#403-not-in-your-plan).

## Timeout Errors

**Symptom:** Requests fail with a timeout error.

**Cause:** The target page takes longer to load than the configured timeout.

**Solution:** Increase `timeout_ms` (default is 15s for single, 30s for browser, 45s for proxy):

```bash
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://slow-site.com",
    "timeout_ms": 60000
  }'
```

For browser requests, also verify your `checkText` value actually appears on the page. A typo will always cause a timeout.

## 403 Not in Your Plan

**Symptom:** The API returns 403 with an `X-FourA-Limit` header and a `reason` of `plan_limit_feature` or `plan_limit_premium`.

```json
{
  "error": "Geo targeting (the exitCountries parameter) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

**Cause:** Your plan doesn't include the endpoint you called or the parameter you sent. `plan_limit_feature` covers an excluded endpoint and `exitCountries` without geo targeting; `plan_limit_premium` covers `exitClass: premium` without premium exits. The target was never contacted, and nothing was spent.

**Solution:** Remove the parameter, call an endpoint your plan includes, or upgrade. The **Limits & Features** tab of [Usage & Limits](/docs/dashboard/quota) lists what your plan includes. Don't retry unchanged: no `Retry-After` is set because waiting doesn't change the answer.

## 429 Too Many Requests

**Symptom:** API returns 429.

**Cause:** One of two checks refused the call, and the response tells you which. If it carries an `X-FourA-Limit` header, one of your plan's limits was reached: simultaneous requests or requests per minute on that endpoint, Browser requests for the day, or the credits or bandwidth for the billing period. If there's no such header, the platform's shared per-minute allowance for that service was full, which is about FourA's traffic and not yours.

**Solution:** Read `X-FourA-Limit` first. Wait when the limit is seconds away and stop when it isn't. Plan limits that a wait clears put the seconds in the `Retry-After` header and in `retry_after_seconds`; the shared limit puts them in `retryAfter`:

```python
import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)
```

If the header said `plan_limit_concurrency` or `plan_limit_rate`, the fix is to cap how many calls you keep open and how many you start per minute rather than to retry harder. Re-sending a refused batch immediately gets the whole batch refused again, and refused calls still count toward the minute. [Run Requests in Parallel](/docs/how-to/run-requests-in-parallel) has the pattern, and **Usage & Limits** in the [Dashboard](https://foura.ai/dashboard) shows your live counters next to your caps.

## 503 Service Unavailable

**Symptom:** API returns 503 status.

**Cause:** This happens in two cases:

1. **The service is at capacity.** FourA is already running as many requests on that engine as it's allowed to run at once, counted across all traffic rather than yours. `Service at capacity` in the `error` field. It usually clears in seconds.
2. **Service temporarily disabled.** A maintenance window is in progress. `Service disabled` in the `error` field.

Both cases include a `retryAfter` field in the response. Neither one is a plan limit: your own plan's limits always answer with an `X-FourA-Limit` header on a 403 or a 429, never with 503.

**Solution:** Wait for `retryAfter` seconds, then retry:

```python
import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")
```

A 503 at capacity is FourA being busy, so backing off and retrying is the whole answer. If you're being refused with 429 and `X-FourA-Limit` instead, that one is yours: reduce the number of parallel requests in your pipeline.

## 504 Upstream Timeout

**Symptom:** The API returns 504 with `{"error": "Upstream timeout"}`.

**Cause:** The work didn't finish inside the time budget you declared for the request. A slow target, a cold challenge solve, or a very large page will all do it. It isn't a problem with your key, your parameters, or your proxy.

**Solution:** Give the call more time, or retry. FourA waits for your `timeout_ms` plus a small margin, so raising it genuinely extends the wait:

```json
{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}
```

For `/api/auto/` on a protected target, a cold first call can take tens of seconds. Its `timeout_ms` covers the whole ladder and accepts up to 180000.

## 502 Upstream Unavailable

**Symptom:** The API returns 502 with `{"error": "Upstream unavailable"}`, or 503 with `{"error": "Backend service unavailable"}`.

**Cause:** FourA reached its own engine but couldn't use the reply, usually because an instance was restarting.

**Solution:** Retry with a short backoff. Both classify as `service_error`, and only `success` is billed, so a retry costs you nothing extra. If it lasts more than a minute or two, check the [status page](https://updates.foura.ai/status).

## 401 Authentication Errors

**Symptom:** Every request returns 401 Unauthorized.

**Checklist:**
1. Verify the header is `X-API-Key: YOUR_API_KEY` (not `Authorization: Bearer` or `Api-Key`)
2. Check for extra whitespace or newlines in your API key
3. Create a fresh key from the [Dashboard](https://foura.ai/dashboard) if the current one might be compromised

## 400 Target Resolves to a Private/Reserved IP

**Symptom:** The API returns 400 with `Target <ip> resolves to a private/reserved IP` before the request leaves FourA.

**Cause:** Your `url` resolves to a private, loopback, or reserved IP range (RFC 5735, RFC 6598, or IPv6 reserved blocks). FourA refuses these targets so its network can't be used to reach internal hosts.

**Solution:** Fetch a public URL. If you're testing, use a public target like `https://example.com` or `https://httpbin.org/get`. If your intended target is a service you run, expose it on a public hostname first.

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

## no_eligible_proxy When Using exitCountries

**Symptom:** A `/api/proxy/` call with `exitCountries` returns HTTP 200 with a JSON error envelope:

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

**Cause:** The current proxy pool has no working exit whose target-visible country matches your allowlist. FourA never falls back to an unrequested country when you set `exitCountries`.

**Solution:** Preserve the requested scope and retry later. The pool is refreshed roughly every ten minutes, so a country that has no match now often gains one within the hour.

```python
import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")
```

Only widen the country list if your workflow's country requirement genuinely changed. Silent fallbacks to other countries can break geo-dependent logic downstream.

## Response Body Comes Back as Garbled Text

**Symptom:** The response `data` (or `body`) contains mojibake or unreadable characters when the target uses a non-UTF-8 charset.

**Cause:** By default FourA auto-decodes response bodies to UTF-8 based on the target's `Content-Type` header or an HTML `<meta charset>` tag. If the target lies about its charset, you get garbled text.

**Solution:** For binary payloads (images, protobuf, raw audio), set `returnBuffer: true` on the request. The body comes back as a base64 buffer with no charset transcoding applied.

```json
{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}
```

For text targets that mis-declare their charset, decode the raw bytes yourself: fetch with `returnBuffer: true`, base64-decode, then apply the correct charset.

## Unexpected HTML Instead of JSON

**Symptom:** You expected JSON from the target site but received HTML.

**Cause:** The target page may serve different content based on headers.

**Solution:** Add an `Accept` header and enable `unblocker` for realistic browser headers:

```bash
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://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'
```

You can also set `tryJsonData` to `true` to have FourA automatically parse JSON responses.

## The Body Is a Challenge Page, Not Content

**Symptom:** The call succeeded, `status` is 200, but `data` (or `body`) is a bot check rather than the page you wanted.

**Cause:** The target ran a bot check that FourA met but couldn't clear. The response says so: Single and Proxy return `defense` with `solved: false`, and Browser returns `defenseSolved: false` with the vendor in `defenses.present`.

**Solution:** Check `defense.vendor` first, then escalate. Try a different browser profile on Single, move up to Proxy for a different exit, or use Browser so JavaScript runs. Full field reference and vendor list: [Anti-Bot Defenses](/docs/api/anti-bot-defenses).

Add a `validate.data.accept` substring that only the real page carries. Without it, a challenge page returned with HTTP 200 counts as a success, and you find out downstream instead of at the call.

## Still Stuck?

If none of the above solutions work:

1. Check the [status page](https://updates.foura.ai) for any ongoing incidents
2. Review your request metrics in the [Dashboard](https://foura.ai/dashboard)
3. Contact support at support@foura.ai with your request details (include the `X-FourA-Request-Id` from the failed response)

## Next Steps

- [Error Handling](/docs/api/errors): API error codes reference
- [Rate Limits](/docs/api/rate-limits): Every plan limit and platform limit, with fields
- [Request Outcomes](/docs/api/outcomes): How outcomes classify what happened
- [Anti-Bot Defenses](/docs/api/anti-bot-defenses): What the `defense` field tells you
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): Pick the best approach for your target
- [Dashboard Overview](/docs/dashboard/overview): Monitor your requests

---

#### Why a Proxy Request Ran Out of Tries
URL: https://foura.ai/docs/troubleshooting/proxy-attempt-report

## The Problem

A `POST /api/proxy/` call comes back with an error and no data. The message is short and always the same shape:

```json
{
  "error": "Download maxTry limit reached",
  "total": 34.812,
  "request": { "...": "..." }
}
```

That sentence reads identically whether every exit was blocked, every exit was dead, or FourA fetched the real page on almost every attempt and your own `validate` rules threw it away. Those three need opposite fixes.

## The Answer: `attemptReport`

Every failed Proxy response carries an `attemptReport` object beside the error. It counts what the attempts actually ran into:

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

The `error` string is deliberately unchanged, so a client matching on it keeps working. Read `attemptReport.summary` for a one-line answer, or the counts when you want to branch on them.

### Fields

| Field | Type | What it counts |
|-------|------|----------------|
| `total` | integer | Attempts made |
| `noResponse` | integer | The exit never answered, so the site was never reached |
| `defense` | integer | The site answered and a bot-check vendor was recognised on that answer |
| `contentRejected` | integer | HTTP 200, no bot check, rejected only by your `validate.data` |
| `statusRejected` | integer | The site answered, no bot check, rejected by your `validate.status` |
| `other` | integer | Answered, and none of the above |
| `vendors` | string[] | Every bot-check vendor recognised anywhere in the task |
| `profilesTried` | string[] | The browser profiles the task sent, in first-use order. `default` means the request went out exactly as you wrote it. |
| `summary` | string | One sentence built from the counts. Safe to log or show a user. |

## Reading It

### `contentRejected` is high

The pages arrived. Your `validate.data` rule didn't match them.

This is the one you can fix yourself, and it's the one every other signal hides: the requests look like failures in every metric, and FourA was delivering real content the whole time. Fetch the page once through `POST /api/single/` with no `validate` at all, look at what actually comes back, and rewrite the rule against it.

A common cause is one rule applied to a set of pages that aren't all the same. A selector that exists on article pages and not on video pages fails every time it lands on a video page, forever, at full cost.

### `statusRejected` is high

The site answered and your `validate.status` rule said no. If those statuses are 401, 403, 429, or 503, the site is refusing the client rather than saying the page isn't there. Try:

- Another browser profile (`browser`, `os`, `version` on the inner `request` object)
- `exitCountries` if the content is region-locked
- `POST /api/browser/` if the refusal needs JavaScript to clear

### `defense` is high

A bot check was recognised on the answers, and `vendors` names which. See [Anti-Bot Defenses](/docs/api/anti-bot-defenses) for what FourA clears today and what it only reports. If the vendor isn't one that gets cleared on this endpoint, move the call to `POST /api/browser/` or `POST /api/auto/`.

### `noResponse` is high

The exits didn't answer at all, so nothing was learned about the target. Raise `maxTries`, raise `timeout_ms`, and check the URL resolves from the public internet.

### `other` is high

Answered, and classified by none of the above. Check `total_time` against your `timeout_ms`: a target slower than your budget lands here.

## Browser Profile Rotation

When a site refuses the browser FourA sent, Proxy stops insisting on it and tries another family from the [public profile catalogue](/docs/api/endpoints). It costs no extra attempt: the rotation changes what a retry sends, never whether one happens.

`profilesTried` is how you see it happen. One entry means the request went out as written every time. Several mean the rotation ran and the site refused each of them, which is a different situation from never having rotated at all.

On a **successful** Proxy response, a `profile` field appears only when the rotation chose a browser you didn't ask for:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "proxy": "A1B2C3",
  "profile": "...",
  "total": 4.108
}
```

The value is a catalogue id from `GET /api/profiles`. Absent means the request went out exactly as written. Present means the browser that worked wasn't the one you typed, so pass that id back as `profile` on follow-up calls rather than replaying the one that failed. The dashboard [Playground](/docs/dashboard/playground) does this for you with **Carry**.

An explicit `profile`, `browser`, `os`, or `version` on your request is never overridden. Neither is a request carrying your own `User-Agent` or `Cookie` header, since a clearance is bound to the signature that earned it.

## Reading It in Code

```python
import requests

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

r = requests.post(f"{API}/api/proxy/", headers=H, json={
    "maxTries": 5,
    "request": {
        "method": "GET",
        "url": "https://example.com/product/42",
        "validate": {"data": {"accept": ["Add to cart"]}},
    },
}).json()

if "error" in r:
    rep = r.get("attemptReport", {})
    print(rep.get("summary", r["error"]))

    if rep.get("contentRejected", 0) > rep.get("total", 0) / 2:
        # The pages arrived. The validate rule is what threw them away.
        raise SystemExit("validate.data did not match the real page")
    if rep.get("defense", 0):
        print("bot check met:", ", ".join(rep.get("vendors", [])))
```

## Related

- [API Endpoints](/docs/api/endpoints): The full Proxy request and response reference
- [Anti-Bot Defenses](/docs/api/anti-bot-defenses): Vendors, `defense`, and replaying a clearance
- [Request Outcomes](/docs/api/outcomes): How a rejected response is classified and billed
- [Common Issues](/docs/troubleshooting/common-issues): Other problems and their fixes
- [Choosing the Right Endpoint](/docs/guides/choosing-task-type): When Proxy is the wrong tool

---

### Updates Portal

#### Updates Portal
URL: https://foura.ai/docs/updates-portal/overview

The [Updates Portal](https://updates.foura.ai) is where you'll find platform news, service status, planned features, and known issues.

## Sections

| Section | What it covers | Link |
|---------|---------------|------|
| [Changelog](/docs/updates-portal/changelog) | Platform updates: new features, improvements, bug fixes | [updates.foura.ai](https://updates.foura.ai) |
| [Service Status](/docs/updates-portal/status) | Current health, uptime history, active incidents | [updates.foura.ai/status](https://updates.foura.ai/status) |
| [Roadmap](/docs/updates-portal/roadmap) | Planned features, vote on what gets built next | [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) |
| [Known Issues](/docs/updates-portal/issues) | Open bugs and their resolution status | [updates.foura.ai/issues](https://updates.foura.ai/issues) |

## RSS

Subscribe to the changelog via RSS at [updates.foura.ai/rss](https://updates.foura.ai/rss) to get notified of new entries in your feed reader. The feed carries the 30 most recent entries with their full text. The feed is English only, whichever language prefix you put in front of it.

## Languages

The portal reads in 13 languages: English, Chinese, Spanish, German, French, Portuguese, Japanese, Russian, Korean, Vietnamese, Polish, Arabic, and Bulgarian. Changelog entries, roadmap items, and issue text are all translated, not just the page furniture.

Pick one from the globe control in the header. Every option is a real link to the same page in that language, so you can open it in a new tab or share it. English lives at the plain path and every other language sits behind its own prefix:

```
https://updates.foura.ai/roadmap      English
https://updates.foura.ai/de/roadmap   German
https://updates.foura.ai/ja/roadmap   Japanese
```

The language comes from the URL alone. A link to the plain path opens in English whatever you picked before, so bookmark or share the prefixed URL for the language you want. The public [API](/docs/updates-portal/api) and the RSS feed serve the English text only.

## Related

- [Quick Start](/docs/getting-started/quick-start): Get started with FourA
- [Dashboard Overview](/docs/dashboard/overview): Managing your account and keys
- [Updates Portal API](/docs/updates-portal/api): Read the changelog, status, roadmap, and issues programmatically

---

#### Changelog
URL: https://foura.ai/docs/updates-portal/changelog

The changelog at [updates.foura.ai](https://updates.foura.ai) lists every platform update in reverse chronological order.

## What You'll See

Each changelog entry includes a title, description, publication date, and category badge.

### Categories

| Category | What it covers |
|----------|---------------|
| New | Features and capabilities that didn't exist before |
| Improved | Improvements to existing features |
| Fixed | Bug fixes and corrections |

Entries can also have tags for more specific labeling.

## How to Use It

### Filtering

Use the filter pills at the top of the page to show only one category. Click **All** to reset.

### Pagination

Entries are paginated with 15 per page. Use the navigation at the bottom to move between pages.

### RSS Feed

Subscribe to [updates.foura.ai/rss](https://updates.foura.ai/rss) in any RSS reader (Feedly, Miniflux, Thunderbird, etc.) to get new entries delivered automatically. The feed includes the full entry body, not just titles.

The RSS feed includes the 30 most recent entries. Older entries aren't included in the feed. Visit the changelog page directly to browse the full history. The feed is English only; the translated entries live on the page under the language prefix.

## Tips

- Check the changelog after receiving a quota warning or noticing behavior changes. New entries often explain what changed.
- Filter by **Fixed** to see recent bug fixes that might affect your integration.
- The RSS feed is the fastest way to stay informed without visiting the portal manually.

## Related

- [Service Status](/docs/updates-portal/status): Current service health
- [Roadmap](/docs/updates-portal/roadmap): What's planned next
- [Updates Portal](/docs/updates-portal/overview): All portal sections

---

#### Service Status
URL: https://foura.ai/docs/updates-portal/status

The status page at [updates.foura.ai/status](https://updates.foura.ai/status) shows the current health of every FourA service and 90 days of uptime history.

## What You'll See

### Service List

Each service shows its name, current status, and a 90-day uptime bar.

### Status Types

| Status | Color | Meaning |
|--------|-------|---------|
| Operational | Green | Running normally |
| Degraded | Yellow | Slower than usual or partially affected |
| Partial Outage | Orange | Some functionality is unavailable |
| Major Outage | Red | Service is down |
| Maintenance | Blue | Scheduled maintenance in progress |

### Uptime Bars

The 90-day bar chart shows one bar per day, color-coded by the worst status that day experienced. Hover over any bar to see the date, status, and downtime duration.

Today's bar reflects the current status in real time and shows the number of active incidents if any exist.

The uptime percentage displayed next to each service counts partial-outage and major-outage minutes as downtime. Degraded minutes lower the day's colour but not the percentage. Only days with recorded data count: days without data (before monitoring started) are drawn without a status colour and excluded from the calculation.

### Active Incidents

If any service is experiencing issues, the status banner at the top of the page turns to the worst current status, and active incident cards appear below the service list. Each card shows the incident title, affected service, start time, and running duration.

### Past Incidents

Resolved incidents from the last 14 days are listed under the active ones, grouped by date. Each shows the incident title, the affected service, when it was resolved, and how long it lasted.

## How to Use It

The page auto-refreshes every 30 seconds, but only service status badges and the overall status banner update automatically. Uptime bars, active incidents, and past incidents don't refresh on their own. Reload the page to update those sections.

If you notice API errors or slow responses, check the status page first. An active incident will tell you whether the problem is on your side or ours.

When the status data can't be fetched, the page answers with a short "Status temporarily unavailable" message and an HTTP 503 with `Retry-After: 30`. Reload after half a minute.

## Tips

- Bookmark [updates.foura.ai/status](https://updates.foura.ai/status) for quick access during incidents.
- If all services show operational but you're still seeing errors, the problem is likely in your request configuration. Check the [Troubleshooting](/docs/troubleshooting/common-issues) page.
- Uptime percentages reset over time as old days fall outside the 90-day window.

## Related

- [Changelog](/docs/updates-portal/changelog): Platform updates and releases
- [Known Issues](/docs/updates-portal/issues): Tracked bugs and resolutions
- [Updates Portal](/docs/updates-portal/overview): All portal sections

---

#### Roadmap & Voting
URL: https://foura.ai/docs/updates-portal/roadmap

The roadmap at [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) shows planned features and lets you vote on what gets built next.

## What You'll See

The roadmap is organized into three columns. Each item includes a title, description, category, and vote count. Items are sorted by vote count within each column, so the most popular items appear at the top.

### Columns

| Column | Meaning |
|--------|---------|
| Planned | On the list, work hasn't started |
| In Progress | Currently being built |
| Done | Shipped and available |

Those three are the whole board. An item that gets cancelled leaves the roadmap rather than moving to a fourth column.

### Categories

Items may have a category label (e.g. "API", "Dashboard", "Developer Experience") to indicate which part of the platform they affect. The label is translated with the rest of the page. If you read the same item through the API you get the underlying slug (`api`, `dashboard`, `developer-experience`) instead.

## How to Use It

### Voting

Click the vote button on any item to add your vote. Click again to remove it. You don't need to be logged in.

Votes are anonymous. Instead of an account, a vote is keyed to your IP address plus the first 50 characters of your browser's User-Agent string. Three practical consequences:

- Clearing cookies or opening a private window doesn't give you a second vote, because neither changes that pair.
- Colleagues sharing an office IP and the same browser family on the same operating system share one vote per item, because those User-Agent strings agree for their first 50 characters. The second person to click removes the first person's vote instead of adding their own.
- After a reload the button shows no vote even if you already cast one. Clicking it then removes your vote, so click once per item.

The same rule applies whether you vote from the page or through `POST /api/roadmap/:id/vote`. Voting is limited to 30 requests per minute per IP address. See the [Updates Portal API](/docs/updates-portal/api) for the endpoint.

Popular items rise to the top of each column, which helps the team prioritize.

### Target Dates

Some items include a target date. These are estimates, not commitments. Check the [Changelog](/docs/updates-portal/changelog) for confirmed releases.

## Tips

- Vote for the features you'd actually use. The vote count directly influences prioritization.
- If you don't see a feature you need, submit a request through the [Issues](/docs/updates-portal/issues) page or contact support.
- Items marked **Done** appear in the [Changelog](/docs/updates-portal/changelog) with release details.

## Related

- [Changelog](/docs/updates-portal/changelog): Released features and updates
- [Known Issues](/docs/updates-portal/issues): Current bugs and their status
- [Updates Portal](/docs/updates-portal/overview): All portal sections

---

#### Known Issues
URL: https://foura.ai/docs/updates-portal/issues

The issues page at [updates.foura.ai/issues](https://updates.foura.ai/issues) tracks known bugs and problems affecting the platform.

## What You'll See

Issues are organized into two tabs:

### Open Tab

Shows issues that are currently active: either **open** (acknowledged) or **investigating** (being worked on).

### Resolved Tab

Shows issues that have been **resolved** or **closed**, with their resolution details. The most recently resolved issues appear first.

Each tab label carries a live count, and each tab has its own URL (`/issues?tab=open`, `/issues?tab=resolved`), so you can link straight to one. Both tabs are paginated with 15 issues per page, with navigation at the bottom.

### Issue Details

Each issue includes:

| Field | Description |
|-------|-------------|
| Title | Brief description of the problem |
| Description | Full explanation of what's happening |
| Severity | How critical the issue is |
| Status | Current state: open, investigating, resolved, or closed |
| Affected Service | Which FourA service is impacted, when the issue is tied to one |
| Opened | When the issue was opened |
| Resolved | When it was resolved (resolved issues only) |
| Resolution | How the problem was fixed (shown on resolved issues) |

### Severity Levels

| Severity | Meaning |
|----------|---------|
| Low | Minor issue with a simple workaround |
| Medium | Noticeable impact, workaround available |
| High | Significant impact on some users |
| Critical | Major functionality broken for many users |

## How to Use It

Switch between the **Open** and **Resolved** tabs to see current problems or learn how past issues were fixed. If you're experiencing an error, check the open issues first to see if it's already tracked.

## Tips

- If you encounter a bug that isn't listed, check the [Service Status](/docs/updates-portal/status) page for broader incidents before reporting it.
- Resolved issues often include the root cause and fix, which can help you understand if your integration needs changes.
- Critical and high severity issues typically have corresponding entries on the [Service Status](/docs/updates-portal/status) page.

## Related

- [Service Status](/docs/updates-portal/status): Live service health and uptime
- [Roadmap](/docs/updates-portal/roadmap): Planned fixes and features
- [Updates Portal](/docs/updates-portal/overview): All portal sections

---

#### Updates Portal API
URL: https://foura.ai/docs/updates-portal/api

The Updates Portal exposes a small public JSON API so you can poll status, ingest changelog entries, watch the roadmap, and check known issues from your own systems. No authentication required. The API serves the English text only; a language prefix in the path is ignored.

## Base URL

```
https://updates.foura.ai
```

## Service Status

`GET /api/v1/status`

Returns the live operational status of every FourA service, plus active and recent incidents. Server-side cached for 15 seconds, so polling more often than that returns the same payload.

```bash
curl https://updates.foura.ai/api/v1/status
```

```json
{
  "overall": "operational",
  "services": [
    {
      "slug": "api",
      "name": "API",
      "description": "...",
      "status": "operational",
      "daily": [
        { "date": "2026-05-19", "status": "operational", "major_outage_minutes": 0, "partial_outage_minutes": 0, "degraded_minutes": 0, "internal_degraded_minutes": 0 }
      ]
    }
  ],
  "active_incidents": [],
  "recent_incidents": [
    { "id": "...", "service_slug": "api", "service_name": "API", "impact": "minor", "started_at": "...", "resolved_at": "..." }
  ]
}
```

| Top-level field | Type | Description |
|-----------------|------|-------------|
| `overall` | string | `operational` if every service is healthy, otherwise one of the service status values |
| `services` | array | One entry per monitored service with `slug`, `name`, `description`, current `status`, and `daily` history (up to 90 days) |
| `active_incidents` | array | Incidents that are currently open |
| `recent_incidents` | array | Resolved incidents from the last 14 days |

Service `status` values: `operational`, `degraded`, `partial_outage`, `major_outage`, `maintenance`.

Incident `impact` values: `minor` (degraded performance), `major` (partial disruption), `critical` (service disruption).

### Polling pattern

Use this endpoint to wire FourA status into your own dashboard or paging system.

When the status data can't be fetched, the endpoint answers `502` with `{"error": "Monitor unreachable"}`. Treat that as an unknown status rather than a bad one, and try again on the next poll.

```python
import requests

def check_foura():
    r = requests.get("https://updates.foura.ai/api/v1/status", timeout=5)
    r.raise_for_status()   # raises on the 502 "Monitor unreachable" answer: retry next poll
    data = r.json()
    if data["overall"] != "operational":
        # Page on-call, post to Slack, flip a feature flag, etc.
        for svc in data["services"]:
            if svc["status"] != "operational":
                print(f"{svc['name']}: {svc['status']}")
    return data
```

The legacy `GET /api/status` returns `410 Gone` and points callers here.

## Changelog

`GET /api/changelog`

Returns published changelog entries in reverse chronological order.

```bash
curl "https://updates.foura.ai/api/changelog?limit=20"
```

Query parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | 1-indexed page number |
| `limit` | integer | 20 | Entries per page (max 50) |
| `category` | string | - | Filter to `new`, `improved`, or `fixed` |

```json
{
  "entries": [
    {
      "id": 42,
      "title": "...",
      "body": "Markdown body",
      "category": "new",
      "tags": "[\"api\",\"dashboard\"]",
      "published": 1,
      "published_at": "2026-05-19T12:00:00Z",
      "created_at": "2026-05-19 11:42:08",
      "updated_at": "2026-05-19 11:44:31"
    }
  ],
  "total": 137,
  "page": 1,
  "limit": 20
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Entry ID |
| `title` | string | Entry title |
| `body` | string | Markdown body |
| `category` | string | `new`, `improved`, or `fixed` |
| `tags` | string | A JSON array **encoded as a string**. Parse it before use: `json.loads(entry["tags"])`. |
| `published` | integer | Always `1` here. The endpoint only returns published entries. |
| `published_at` | string | ISO 8601 with a `Z` suffix |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`, UTC, with no zone marker |
| `updated_at` | string | Same format as `created_at` |

The two timestamp formats are different on purpose: `published_at` is the editorial date and carries a zone, while `created_at` and `updated_at` are storage timestamps. Both are UTC. A parser that assumes one format for all three will throw on the other two.

### RSS

The full changelog (30 most recent entries) is also published as RSS at:

```
https://updates.foura.ai/rss
```

Subscribe in Feedly, Miniflux, Thunderbird, or any reader. The feed body matches the changelog body, including markdown rendered to HTML.

## Roadmap

`GET /api/roadmap`

Returns every published roadmap item, sorted by vote count then creation time.

```bash
curl https://updates.foura.ai/api/roadmap
```

```json
{
  "items": [
    {
      "id": 12,
      "title": "...",
      "description": "...",
      "status": "planned",
      "category": "developer-experience",
      "votes": 23,
      "target_date": "Q3 2026",
      "completed_at": null,
      "created_at": "2026-03-30 09:32:47"
    }
  ]
}
```

Item `status` values: `planned`, `in_progress`, `done`, `cancelled`. The board at [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) renders three columns, so an item set to `cancelled` reaches you through this endpoint and never appears on the page.

`category` is a lowercase slug, not the label the page prints. Slugs in use today: `api`, `infrastructure`, `developer-experience`, `dashboard`, `billing`, `analytics`, `authentication`. Treat the list as open, since a new item can introduce a new one.

`target_date` is free text (`"Q3 2026"`), not a date. `completed_at` is `null` until an item ships, then ISO 8601 with a `Z` suffix (`2026-09-01T10:15:30.000Z`), the same format as a changelog entry's `published_at`. `created_at` uses `YYYY-MM-DD HH:MM:SS` in UTC. The two formats differ inside one object, so parse each field on its own.

### Voting

`POST /api/roadmap/:id/vote`

Toggles a vote on a single roadmap item. Votes are anonymous and tied to the caller's IP plus the first 50 characters of its User-Agent. Calling again removes the vote. An unknown or unpublished item answers `404 {"error": "Not found"}`.

```bash
curl -X POST https://updates.foura.ai/api/roadmap/12/vote
```

```json
{ "votes": 24, "voted": true }
```

`voted` reports the post-call state: `true` if your vote was added, `false` if it was removed.

The roadmap endpoints, `GET /api/roadmap` and this one, are limited to 30 requests per minute per source IP. Over that, the answer is `{"error": "Too many votes, slow down"}`.

## Known Issues

`GET /api/issues`

Returns issues tracked by FourA support.

```bash
curl "https://updates.foura.ai/api/issues?tab=open"
```

Query parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `tab` | string | `open` | `open` for active issues, `resolved` for resolved/closed |

```json
{
  "issues": [
    {
      "id": 5,
      "title": "...",
      "body": "Markdown description",
      "severity": "medium",
      "status": "investigating",
      "service_id": 3,
      "resolution": "",
      "opened_at": "2026-05-18T09:00:00Z",
      "resolved_at": null,
      "service_name": "API"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Issue ID |
| `title` | string | Short summary |
| `body` | string | Markdown description |
| `severity` | string | `low`, `medium`, `high`, or `critical` |
| `status` | string | `open`, `investigating`, `resolved`, or `closed` |
| `service_id` | integer or null | Numeric ID of the affected service. `null` when the issue isn't tied to one. |
| `service_name` | string or null | The service's display name, resolved for you. Read this instead of mapping `service_id` yourself. |
| `resolution` | string | How it was fixed. Empty string while the issue is open. |
| `opened_at` | string | ISO 8601 with a `Z` suffix |
| `resolved_at` | string or null | ISO 8601 with a `Z` suffix, `null` while open |

`service_id` is a numeric foreign key, not the slug you see on the status page. Match issues to services by `service_name`.

The issue payload is a fixed column list and carries no modification timestamp. Order or age an issue by `opened_at` and `resolved_at`. Of the three public collections, only changelog entries return `created_at` and `updated_at`.

The `resolved` tab returns the 30 most recently resolved issues and stops there. The `open` tab returns all of them.

## Notes

- All endpoints are public and need no API key. The roadmap endpoints are limited to 30 requests per minute per source IP; the others carry no rate limit of their own today, so poll status no more often than its 15-second cache warrants.
- Responses are JSON over HTTPS. Roadmap and issues take no paging parameters. The one cap is `?tab=resolved` on issues, which returns 30 rows.
- For free-text or raw HTML versions of the changelog, use the [`/rss`](https://updates.foura.ai/rss) feed instead of `/api/changelog`.

## Related

- [Service Status](/docs/updates-portal/status): Read the same data in the browser
- [Changelog](/docs/updates-portal/changelog): Browse entries with filters and pagination
- [Roadmap](/docs/updates-portal/roadmap): Vote on items in the UI
- [Known Issues](/docs/updates-portal/issues): Read open and resolved issues
- [Updates Portal](/docs/updates-portal/overview): Section overview

---

## Blog

### Grocery Price Scraping: Which Store, Which Shopper?
URL: https://foura.ai/blog/grocery-price-scraping-store-shopper
Category: use-case

A dozen Lucerne eggs at one Safeway in Washington, D.C. was offered on Instacart at $3.99, $4.28, $4.59, $4.69 and $4.79. Same store, same moment, different shoppers. Which of those five numbers belongs in your price panel?

## The Challenge

Grocery is where price intelligence stops being "fetch the product page, parse the price." A grocery price belongs to a store, often to a delivery zone, and more and more to whoever is looking at it.

Start with the store. Scrapfly's [grocery price comparison guide](https://scrapfly.io/blog/posts/how-to-build-a-grocery-price-comparison-tool-with-python) puts a gallon of milk at $3.98 in one Walmart and $4.29 in another 20 miles away, and warns that a session with no store location gets default data that may not match any real store. ScrapeInsight's [2026 grocery delivery guide](https://scrapeinsight.com/blog/scrape-grocery-delivery-data/) sees the same thing a level down: $3.99 in one delivery zone, $4.49 a few miles over. Bright Data's [ShopGrok case study](https://brightdata.com/customer-stories/general/shopgrok) describes Australian retail pricing turning postcode-dependent over that company's almost four years in business.

Then the shopper. In December 2025, Groundwork Collaborative, Consumer Reports and More Perfect Union [put 437 shoppers through live tests in four cities](https://groundworkcollaborative.org/work/instacart/), filling identical Instacart carts from the same stores at the same time. 74% of the items appeared at more than one price. Where prices differed, the gap between lowest and highest averaged 13%, and whole baskets varied by about 7%.

Put those together and you get the failure that makes grocery data expensive. Lose the store context and nothing breaks. The site doesn't return an error. It returns a perfectly good price for a store you didn't ask about, with a SKU, a number and a timestamp that pass every null check you own.

We've written about the version where [a block looks like a data point](/blog/alternative-data-silent-collection-gaps). This one is harder to catch, because the page really is a price page. Just not yours.

## Prove the Store Inside the Response

Most collectors send the store selection (a cookie, a query parameter, a header) and trust it. The sturdier habit is to make the response prove it. If the page names the store it was rendered for, say a store ID in the embedded data or a store name in the pickup banner, that marker becomes your definition of success. On FourA that's one Proxy Finder call:

```python
import requests

r = requests.post(
    "https://api.foura.ai/api/proxy",
    headers={"X-API-Key": "pk_live_..."},
    json={
        "maxTries": 6,
        "request": {
            "method": "GET",
            "url": "https://grocer.example/product/0001234",
            "headers": [["Cookie", "store=1234"]],
            "validate": {
                "status": {"accept": [200]},
                "data": {
                    "accept": ["\"storeId\":\"1234\""],
                    "fail": ["Just a moment", "Access Denied"]
                }
            }
        }
    }
).json()

if "error" in r:
    report = r.get("attemptReport", {})
    print(report.get("summary", r["error"]))
    if report.get("contentRejected", 0) > report.get("defense", 0) + report.get("noResponse", 0):
        print("the site answered for another store: check the store selection")
else:
    page, exit_id = r["data"], r["proxy"]
```

Three details in that request are easy to get wrong.

`accept` passes when any one of its strings appears in the page. Put a price marker next to the store marker and a wrong-store page sails through, because it has a price too. Keep the store marker alone in `accept`, and put the challenge strings in `fail`.

Your own `Cookie` header changes how retries behave. When a site refuses the browser we presented, Proxy Finder normally moves to another browser family on the next attempt. Not with your cookie attached. A session is bound to the signature that earned it, so a request carrying its own cookie keeps the browser it started with. If a chain's site turns out to be fussy about browsers, pick one explicitly with [browser profiles](/blog/browser-profiles-per-request) rather than counting on rotation.

And a failed task tells you which failure you have. Every failed Proxy Finder response carries an `attemptReport`. `defense` counts answers where a bot check was recognised, `noResponse` counts exits that never reached the site, and `contentRejected` counts pages that came back as HTTP 200 with no bot check and were thrown out only by your content rule. For a grocery collector that last count means something specific: the site answered, just not for your store. More exits won't fix that. The [attempt report guide](/docs/troubleshooting/proxy-attempt-report) covers the other counts.

## Hold the Shopper Still, or Measure the Spread

The Instacart findings add a second variable, and there are two honest ways to handle it.

For a price panel, keep each store's collection on one identity. Replay the exit that delivered (`r["proxy"]`, an opaque ID) through Single with the same cookie, and store that ID plus the `X-FourA-Request-Id` response header with every row. When a price jumps, you can tell a change at the store from a change of session.

For pricing research, do the opposite on purpose. Sample the same SKU in the same store through several independent sessions and keep the distribution, not the first answer. A panel that reports one number where shoppers see five isn't precise. It's lucky.

## Results

Take a regional chain benchmarking 120 competitor stores on 2,500 SKUs, refreshed daily (illustrative scenario based on industry benchmarks). That's 300,000 page reads a day, and on any given night some of them will come back for the wrong store: a cookie format changed, a store closed, a site started preferring IP location over the cookie.

- **Wrong-store pages fail at collection.** They never become rows, so a price move in the panel is a move at that store.
- **Failures arrive sorted.** High `contentRejected` goes to whoever owns store selection, high `defense` is an access problem, high `noResponse` is exits. Three owners, three fixes, and nobody spends a morning guessing which one it is.
- **Every row is traceable.** An exit ID and a request ID per observation turn "is this spike real?" into a lookup.
- **Spread becomes a number you have.** For the SKUs you sample across sessions, you can report the range shoppers actually meet instead of one reading from it.

Where this runs out: member and loyalty prices sit behind accounts, and experiments keyed to a logged-in shopper won't show up in anonymous sessions at all. Collecting those is a terms-of-service question before it's an engineering one. And a store marker is only as good as your choice of it. Take it from the page source, not from memory, and check it again whenever the chain redesigns.

## Key Takeaway

A grocery price used to be a fact about a product. Now it's a fact about a product, a store and a shopper, and a collector that records only the first is producing noise with a very tidy schema.

If per-shopper pricing keeps spreading, the question buyers ask of grocery data moves from "what does it cost?" to "what does it cost here, and how wide is the range?" So the collectors worth trusting won't be the ones with the most exits. They'll be the ones whose every request can say which store it was for, and prove it.

---

### ScraperAPI geotargeting vs FourA: what one country costs
URL: https://foura.ai/blog/scraperapi-vs-foura-geotargeting
Category: comparison

## What does one country cost on ScraperAPI and FourA?

$299 a month against $99. Those are the first plans on ScraperAPI and on FourA that let you target one specific country (Germany, the UK or Japan, say), read from both pricing pages on 14 September 2026. If your targets change prices, stock or search results by country, that gap is most of the decision.

## How FourA prices country targeting

Proxy Finder takes an `exitCountries` list of two-letter codes, like `["DE"]` or `["CZ", "GB"]`. Our [endpoint reference](https://foura.ai/docs/api/endpoints) calls it a strict allowlist: an exit with an unknown country is left out, the request never falls back to a country you didn't ask for, and the response carries the `exitCountry` that answered, so you can check it.

It's included from the Startup plan, $99 a month or $799 for the year, with 450,000 credits, as of 14 September 2026 on [foura.ai/prices](https://foura.ai/prices). A Proxy Finder call costs [5 credits, or 10 with the unblocker](https://foura.ai/docs/api/response-headers), and the country list adds nothing to that. So $99 covers 90,000 country-targeted calls a month, or 45,000 with the unblocker on every one.

## How ScraperAPI geotargeting is priced

ScraperAPI's [pricing page](https://www.scraperapi.com/pricing/) marks geotargeting "US & EU only" on Hobby ($49 a month, 100,000 credits) and on Startup ($149, 1,000,000 credits). The [Standard Geo docs](https://docs.scraperapi.com/control-and-optimization/geotargeting/standard-geo) say what that means in practice: those plans get a `us` code and an `eu` code for "Europe (general)", and "individual country codes are not supported". All 68 single countries on that page start at Business, which is $299 a month for 3,000,000 credits and 100 concurrent threads.

The code itself is free there. ScraperAPI's [credits page](https://docs.scraperapi.com/getting-started/quick-start/credits-and-requests-costs) files `country_code` under "No Extra Cost", on top of 1 credit for a plain request.

## Why FourA comes out ahead here

Take a price tracker checking 1,500 product pages on German shops once a day. That's about 45,000 calls a month, which fits inside FourA's Startup at $99 even with the unblocker on every call. On ScraperAPI the `de` code needs Business at $299, because Hobby and Startup stop at Europe in general. You'd pay $200 more every month ($2,400 a year) for the right to name the country. And the gap doesn't close as you grow: FourA's Business plan, $249 a month, covers 450,000 country-targeted calls and still costs less than ScraperAPI's Business.

ScraperAPI gets two things right here, and they're worth weighing. A country costs no extra credits, and its docs publish every supported country next to the plan it starts on, so you know before you pay whether your market is covered. Its regional `us` and `eu` codes also sit on every plan from Hobby, which is plenty when a target only cares which side of the Atlantic you're on.

## Run the same request on FourA

Go through last month's logs and count the calls where the country mattered. Then split that count in two: calls that needed one specific country, and calls that would've done fine with "somewhere in Europe". The first number picks your plan. Under 90,000 a month it's $99 on FourA against $299 on ScraperAPI, and under 450,000 it's $249 against $299. If you're wondering why the country a target sees matters beyond price, we covered that in [Ad Verification at Scale: The Geo-Authenticity Problem](https://foura.ai/blog/ad-verification-geo-authenticity).

## Frequently asked

**Does picking a country cost extra credits?** Not on either side. ScraperAPI lists `country_code` under "No Extra Cost", and FourA's credit table prices a Proxy Finder call by the unblocker alone, with no line for the country.

**What if FourA has no exit in the country I asked for?** The call doesn't quietly leave from a neighboring country. It comes back with a `no_eligible_proxy` error that echoes your codes, and since [only a success is billed](https://foura.ai/docs/api/outcomes), that answer isn't billed.

**Can I target a city?** ScraperAPI's [geolocation FAQ](https://docs.scraperapi.com/resources/faq/geolocation-and-residential-ips) says it doesn't support state or city targeting. FourA's API stops at the country as well, while the [Proxy port](https://foura.ai/docs/dashboard/proxy), a beta that isn't billed yet and carries no uptime commitment, lets a residential credential narrow to a region and a city.

So try it on a market you actually sell into: create a free account at [auth.foura.ai/signup](https://auth.foura.ai/signup), send one of your own URLs through Proxy Finder on the free plan's 3,000 credits, and add `exitCountries` once you're on Startup.

---

### FourA Digest — Sep 4 to Sep 11, 2026
URL: https://foura.ai/blog/foura-digest-2026-09-11
Category: digest

## Highlights

Was that the site saying no, or your plan? Every request your plan refuses now answers in one header, and Auto and the Playground read that answer too. The proxy port learned to remember targeting on the key, and Browser rendering plus CAPTCHA solving come with every plan, Free included.

## What's New

### A refusal that names who refused

When one of your plan's limits turns a request away, the response carries an `X-FourA-Limit` header saying which one: `plan_limit_credits`, `plan_limit_rate`, `plan_limit_browser_daily` and four others. The body repeats the code under `reason`, beside the number you're held to. Our shared platform limits never set that header, so its presence alone tells you the refusal is about your account, not about FourA being busy.

```python
import requests

r = requests.post(
    "https://api.foura.ai/api/single",
    headers={"X-API-Key": "pk_live_..."},
    json={"url": "https://example.com/data"},
)
limit = r.headers.get("X-FourA-Limit")
if limit:
    print("my plan stopped this:", limit, r.json()["error"])
```

Every limit on your account now comes from the plan you're on, and Usage & Limits lists each one next to where you stand this period. The [rate limits reference](https://foura.ai/docs/api/rate-limits) has all seven codes and which ones a short wait clears.

Auto reads the same code and acts on it. A limit that shuts one rung (the day's browser allowance, say) leaves the rest of the ladder working, and the exits it already tried aren't blamed for a refusal your plan issued. A limit that means the account itself is out, like credits, bandwidth or a product your plan doesn't include, stops the ladder at once and hands you the refusal rather than trying every other route first. None of this changes [what Auto is for](https://foura.ai/blog/auto-endpoint): let it find the rung that works, then replay the session it returns on `/api/single` or `/api/browser` and point your volume there.

The Playground puts it in words. A line above the response says what carried the page: a session we already had for that host, a plain request, a rotating proxy or a real browser, plus whether a challenge was solved, which attempt got through and what it cost. When your plan stopped the request, the line opens with "Stopped by your plan, not by the site" and names the limit.

### The proxy port, in beta

The proxy port lets any client that takes a proxy URL send its traffic through our exits, with no API call involved. It's a beta: traffic through it isn't billed yet, it carries no uptime commitment, and option names can still change.

This week it got clearer about what you're choosing: the shared network, which is our own exits and comes with your plan, or the residential network, home addresses drawn from your plan's premium traffic. Falling back to residential when the shared network can't carry a request is a separate switch, and it starts unticked. A box we tick for you would be us deciding to spend your allowance.

Targeting lives on the credential now. Save a country, region, city or device on a proxy user and every connection made with it answers that way. So the connection string shrinks to the bare credential plus whatever differs. But the username still wins for that one connection, and `any` takes a saved value back: `-city-any` asks for the whole country from a key that remembers one city.

Running a browser profile per address? Set how many sticky addresses you want and the page lists one line each, with its own session name. New names hands you a fresh set when a target has soured on the old one, and the lines come as a URL or as `host:port:user:pass`, the shape most proxy managers import. The [proxy port docs](https://foura.ai/docs/api/proxy-port) have the whole username grammar.

### Defended pages, on every plan

Browser rendering and CAPTCHA solving are part of every plan, Free included, and only the limits differ. Free and Developer carry some premium exit traffic as well, so you can watch a defended page come back on your own URL before you pay anything.

Premium exits on Proxy Finder stopped caring which site you point them at. Send `exitClass: premium` for any target and your plan's premium traffic (and what's left of it) is the only thing that decides.

### Billing that follows your details

The company, VAT number and country you save under Billing Details are what we print on your invoice and what decides your VAT treatment, at checkout and on every renewal. Type something different into the payment form and it overrides that one field for that one payment.

If we've set you up on a plan as part of a signed deal, Plan & Usage now offers it back with a Confirm button: pick monthly or annual, add a card, and you pay the full period up front, nothing prorated.

Two new cards sit beside credits on Plan & Usage, one for bandwidth and one for premium traffic, each showing what you've used against what your plan includes plus anything you bought. When a top-up for that kind is on sale, the Buy button is on the card it raises. The [billing guide](https://foura.ai/docs/dashboard/billing) walks through both.

## Under the Hood

Your per-minute rate limit counts exactly the traffic you sent in that minute, right up to the turn of the next one. Dashboard tables fit a laptop screen, and on a phone the wide ones scroll sideways inside their own frame. Blog tables scroll the same way on narrow screens. And your organization page lists pending invitations the moment it opens.

A refusal you can read is one you can plan around. Next time a job stops, one header tells you whether to wait a second, wait for midnight UTC, or go and look at your plan.

---

### Firecrawl vs FourA: what 1,000 fetched pages cost
URL: https://foura.ai/blog/firecrawl-vs-foura-page-cost
Category: comparison

## What 1,000 fetched pages cost on Firecrawl and FourA

$3.80 against $0.39. That's what a thousand plain page fetches cost on Firecrawl's entry plan and on FourA's, from both pricing pages as of 10 September 2026. If your targets are documents (listing pages, search results, JSON endpoints), that ratio is most of the decision.

## What FourA charges to fetch a page

A plain fetch through Single is 1 credit. Switch the unblocker on and it's 2. Send it through Proxy Finder and it's 5. The [credit table](https://foura.ai/docs/api/response-headers) is public, and every response carries an X-FourA-Credits header with what that call spent, so you read the meter as you go instead of rebuilding it from an invoice.

Developer is $29 a month, or $239 for the year, for 75,000 credits, as of 10 September 2026 on [foura.ai/prices](https://foura.ai/prices). At a credit a page that's 75,000 fetches, so $0.39 per 1,000. Run every one of them with the unblocker and it's 37,500 pages at $0.77 per 1,000. Push the stubborn ones through Proxy Finder at 5 credits and the same $29 still covers 15,000, at $1.93 per 1,000.

## What Firecrawl charges for the same page

A credit a page, on every plan. Firecrawl's [pricing page](https://www.firecrawl.dev/pricing) is direct about it: one credit is one page on a basic scrape, crawl or map, and the rate table doesn't shift between tiers. Search costs 2 credits per 10 results, and the JSON, Question and Highlight formats add 4 credits a page.

Hobby is $19 a month, or $16 billed annually, for 5,000 credits and 5 concurrent requests, read on September 10, 2026. That works out to $3.80 per 1,000 pages. Standard, the next one up, lists 100,000 credits at $83 a month billed annually.

| | Firecrawl Hobby | FourA Developer |
|---|---|---|
| Monthly price | $19 | $29 |
| Credits | 5,000 | 75,000 |
| Plain page | 1 credit | 1 credit |
| Per 1,000 pages | $3.80 | $0.39 |
| Concurrent | 5 | 10 |

## Why FourA comes out ahead here

Same unit, same job, and 10 concurrent requests against 5. But the entry plans flatter us, so take the annual rates instead: a year of Standard is $83 a month for 100,000 credits, which is $0.83 per 1,000 pages, and a year of Developer is $239 for 900,000 credits, which is $0.27. The gap narrows from roughly ten times to roughly three, at the tier you'd actually land on. Three times is still the difference between a line item and a budget.

Firecrawl gets two things right that are worth saying out loud. It publishes one rate table that holds on every plan, which is rarer than it ought to be, and its Markdown output arrives ready for a model with no parsing step in between. Its free tier refreshes monthly with no card, and SOC 2 Type II, MFA and signed webhooks sit on every plan including that one.

## Run the same request on FourA

Pull a week of your own logs and count two things: pages you fetched, and pages that genuinely needed a browser to render. Multiply the first by $0.0038 and then by $0.00039, and the difference between those two figures is the line item you're deciding. The second count is the one that moves the arithmetic, so measure it before you take anyone's per-page number, ours included.

## Frequently asked

**What does an error page cost on each side?** Firecrawl returns a page carrying a status such as 403 or 404 and bills it a credit, effective 4 September 2026. On FourA [only a success is billed](https://foura.ai/docs/api/outcomes), and you get to say what success means, which we wrote up in [Validate Rules Now Decide What Counts as Success](https://foura.ai/blog/validate-decides-success).

**How far does each free plan go?** Firecrawl's free plan is 1,000 credits a month, no card, 2 concurrent requests. FourA's is 3,000 credits, with Browser, CAPTCHA solving and the unblocker switched on from the start.

So go run it rather than trusting anyone's arithmetic, ours very much included: create a free account at [auth.foura.ai/signup](https://auth.foura.ai/signup), send 100 of your own URLs through Single, and add up the X-FourA-Credits headers that come back.

---

### What a 404 costs on ScraperAPI, Zenrows and FourA
URL: https://foura.ai/blog/scraperapi-zenrows-404-cost
Category: comparison

## Who pays for the page that isn't there

You're choosing between ScraperAPI, Zenrows and FourA, and your target list has dead links in it: delisted products, expired job posts, moved pages. Every crawl does. One question, then: what each of us charges when the target answers 404, from their pricing docs and ours, read on 9 September 2026.

## What FourA charges when the target says no

Every request to FourA gets one of seven outcomes, and [only success is billed](https://foura.ai/docs/api/outcomes). Without a validate rule, a request counts as success only when the target returns HTTP 200. A 404 is an application failure. So is a 500, a 403, and a challenge page your rule rejected. None of them bills or counts against your plan.

That includes the request you cancel. Hang up before the response arrives and the outcome is a service failure, which is free.

What you pay is set per engine: [Single is 1 credit, 2 with the unblocker, Proxy Finder 5 or 10, Browser 15, or 30 when it solved a defense](https://foura.ai/docs/api/response-headers). Every response carries an X-FourA-Credits header that meters what the work spent, and the Dashboard shows Billed next to Spent, so you can read the gap yourself.

If a 404 is data to you (you're checking which listings went away), you say so: put 404 in validate.status.accept and that response comes back as a billed success. You decide what counts, not the status code. We wrote up the mechanism in [Validate Rules Now Decide What Counts as Success](https://foura.ai/blog/validate-decides-success).

## What ScraperAPI and Zenrows charge for the same response

ScraperAPI's [credits page](https://docs.scraperapi.com/getting-started/quick-start/credits-and-requests-costs) says it plainly: "We only charge for successful requests (200 and 404 status codes) and for requests that have been cancelled from your side before giving us enough time to finish them (70 seconds)." A plain page is 1 credit, render=true is 10, and a bypass on a site behind Cloudflare, DataDome or PerimeterX adds 10 per request. Their [status codes page](https://docs.scraperapi.com/responses-and-formats/api-status-codes) repeats the 404 rule and adds that a request still failing after 70 seconds of retries isn't charged. On the [Hobby plan](https://www.scraperapi.com/pricing/), $49 a month buys 100,000 credits, as of 9 September 2026.

Zenrows draws the same line. Its [pricing docs](https://docs.zenrows.com/first-steps/pricing) read: "HTTP 404 and 410 responses count as successful because the request completed correctly and returned valid data." Its credit table is headed "credits per successful request": a standard request is 1, JavaScript rendering 5, premium proxies 10, both together 25, and the [pricing page](https://www.zenrows.com/pricing) says those weights are fixed.

| | ScraperAPI | Zenrows | FourA |
|---|---|---|---|
| Plain 404 | 1 credit | 1 credit | 0 |
| Rendered 404 | 10 credits | 5 credits | 0 |
| Cancelled by you | billed under 70 s | not stated | 0 |
| 404 you asked for | 1 credit | 1 credit | billed, by your rule |

## Why FourA comes out ahead here

Say 5,000 of your URLs this month are dead. Rendered on ScraperAPI, by the two rules above, that's 50,000 credits, half of the Hobby plan's 100,000, spent on pages that don't exist. On Zenrows the same 5,000 are 25,000 credits at the rendering weight. On FourA they bill zero, unless you told us a 404 is what you wanted, and then they bill because they were the data. That isn't a discount. It's a different answer to who defines success: the status code, or you.

Credit where it's earned. ScraperAPI publishes a cost lookup endpoint and a max_cost cap, so you can price a URL before you fetch it, and returns each request's cost in an sa-credit-cost header. Zenrows prints one credit table, promises the weights won't move, and doesn't charge for a failed attempt either. Both are clear about the rule. We draw the line elsewhere.

## Run the same request on FourA

Pull a week of your own logs and count two things: responses that came back 404 or 410, and requests your client gave up on. Multiply the first by the weight you'd have sent (1, 5, 10 or 25) and that's the part of the bill that buys nothing. On FourA that line is zero, and the outcome label on each request in the Activity log tells you why.

Then check it yourself: create a free account at [auth.foura.ai/signup](https://auth.foura.ai/signup), send one of your dead URLs through Single, and watch Billed stay put on Usage & Limits while Spent moves.

---

### Web Scraping Pricing: Per GB, Per Page, or Per Request?
URL: https://foura.ai/blog/web-scraping-pricing-per-gb-vs-per-page
Category: comparison

## Nobody Sells Web Scraping in the Same Unit

Bright Data prices its Web Unlocker per thousand requests. Oxylabs prices Web Unblocker per gigabyte. Firecrawl charges one credit per page. Zyte charges per thousand successful responses, split across five difficulty tiers. Apify bills a compute unit, which is one gigabyte of RAM held for an hour.

Five vendors, five units. Not one of them converts into another without a number you have to go measure yourself, and none of them publishes that number, because it belongs to your traffic rather than to their product.

We read all five pricing pages on September 8, 2026. Here's what they say, and what the arithmetic does to them.

## Quick Comparison

| Vendor / product | Billing unit | List price, September 8, 2026 |
|---|---|---|
| [Bright Data Web Unlocker](https://brightdata.com/pricing/web-unlocker) | per 1K requests | $1.50/1K pay-as-you-go, $1.30/1K on the $499 plan |
| [Bright Data Browser API](https://brightdata.com/pricing/web-unlocker) | per GB | from $5/GB |
| [Oxylabs Web Unblocker](https://oxylabs.io/products/web-unblocker/pricing) | per GB | $9.40/GB at 8GB, $8.60/GB at 38GB, $7.50/GB at 88GB |
| [Oxylabs Web Scraper API](https://oxylabs.io/products/web-unblocker/pricing) | per 1K results | from $0.25/1K |
| [Firecrawl](https://www.firecrawl.dev/pricing) | per page (1 credit) | $83/month billed yearly for 100K credits, so $0.83 per 1K pages |
| [Zyte API](https://www.zyte.com/pricing/) | per 1K successful responses, 5 site tiers | $0.13 to $1.27/1K over HTTP, $1.01 to $16.08/1K rendered |
| [Apify](https://apify.com/pricing) | compute unit (1 GB of RAM for an hour) | $0.20/CU, $0.13/CU on the $999 plan |

Two things jump out of that table.

Zyte's own list spans 124x. Same vendor, same unit, same line on the same invoice: a simple site fetched over HTTP is $0.13 per thousand, an advanced site rendered in a browser is $16.08. Anyone who quotes "per thousand requests" as a comparable number is quoting one end of a range that wide.

And Bright Data switches units halfway through its own catalogue. Unlocker is sold per request. Browser API is sold per gigabyte. That isn't sloppiness. It's the tell, and the rest of this post is about what it tells you.

## What a Gigabyte Actually Buys

The number that decides every conversion is your average page weight, and the public data on it is brutal.

HTTP Archive's [Web Almanac 2025](https://almanac.httparchive.org/en/2025/page-weight) puts the median mobile home page at 2,559 KB as of the July 2025 crawl, up 8.4% in a year. Break that median page down by content type and you get 911 KB of images, 632 KB of JavaScript, 122 KB of fonts, 77 KB of CSS.

And 22 KB of HTML.

That last number is the one that matters, because the HTML document is usually the only part you parse. On the median page it's 0.86% of the bytes a full browser render pulls down. The other 99% is furniture you paid to move.

Run that through the Oxylabs 8 GB plan at $9.40/GB:

- Fetching HTML only, at 22 KB a page, one gigabyte is roughly 45,000 pages. That's about **$0.21 per 1,000 pages**.
- Rendering the whole page, at 2,559 KB, one gigabyte is roughly 390 pages. That's about **$24 per 1,000 pages**.

Same plan. Same advertised price. A 116x spread, decided entirely by a setting in your own code.

Now put Firecrawl next to it. At $83 for 100,000 credits on the annual rate, one credit a page, you pay $0.83 per 1,000 pages whether the page weighs 20 KB or 4 MB. Against HTML-only fetching, the per-gigabyte meter is about four times cheaper. Against full rendering, it's about 29 times more expensive.

## The Crossover Sits Near 100 Kilobytes

Do the algebra and the two meters meet at a specific page weight. Firecrawl's $0.00083 a page divided by Oxylabs' $9.40 a gigabyte is 88 KB. Take Firecrawl month to month rather than annually ($99.50 for the same 100,000 credits) and the crossover moves to 106 KB. Below that band, per-gigabyte billing wins. Above it, flat per-page billing wins, and the gap widens fast, because page weight has no ceiling.

Here's the part we like. Oxylabs publishes its own conversion without framing it as one: the Web Unblocker free trial is described as "1GB (up to 10k results)". That's 100 KB per result, landing inside the band we just worked out from two other vendors' price lists. Their own arithmetic assumes you're fetching documents, not rendering galleries.

So if you're on a byte meter and you're driving a browser, the single biggest lever isn't your vendor. It's blocking images and fonts before the page loads, because on the median page that's 1,033 of the 2,559 KB. We'd rather tell you that than pretend the choice of logo on the invoice is what decides the bill.

Two honest caveats. These are median figures across the whole web, and your targets are not the whole web (retail and travel pages run heavier, JSON endpoints far lighter). And a rendered page with media blocked can land well under the median, which moves the crossover in your favor without changing anything on the pricing page. The same arithmetic decides [when an LLM extraction step stops paying for itself](https://foura.ai/blog/llm-extraction-stops-paying-at-scale): the unit price is never the interesting number, the price per record you kept is.

## What Counts as Billable Is a Second Axis

Unit is one question. What triggers the meter is a different one, and it's easier to miss.

Bright Data advertises "pay only for success" on Unlocker. Zyte prices "per 1,000 successful responses". Firecrawl spends a credit per API request, by endpoint. On a per-gigabyte meter there is no success condition at all: the bytes moved, so you're billed, and a challenge page you throw away is a page you bought.

That matters more than it sounds, because a challenge or an interstitial usually arrives with HTTP 200 attached. If your definition of success is the status code, your retry logic and your invoice will disagree with your dataset. We wrote about that split in [Validate Rules Now Decide What Counts as Success](https://foura.ai/blog/validate-decides-success), and it's the same fault line that turns a partial block into [a silent hole in a time series](https://foura.ai/blog/alternative-data-silent-collection-gaps).

## Who Should Buy Which Unit

**Buy per gigabyte** if you fetch documents rather than render them, and your targets are text: search results, JSON endpoints, listing pages, sitemaps. At 20 to 50 KB a page, byte pricing is the cheapest thing on the market and nothing else is close.

**Buy per page or per request** if you render, if your targets are media-heavy, or if you simply can't predict page weight across a long tail of sites. You're paying a premium at the small end to buy a ceiling at the large end, and on a rendering workload that ceiling is worth a lot.

**Buy per tier**, as Zyte sells it, if your target mix is stable and you know which tier each site falls into. The model is honest about the thing everyone else averages away, which is that hard sites cost more to collect. It's a poor fit when your target list churns weekly.

**Buy compute units** if you run long crawls with your own code on the platform. That meter bills the machine, not the data, so it rewards a fast parser and punishes a slow one. It's the only model on this list where optimizing your code shows up directly on the invoice.

None of these units is a trick. Each one is a bet about what typical traffic looks like, made by a vendor who knows their own customer base. The mistake isn't picking the wrong unit. It's comparing two quotes that were never in the same unit and calling the cheaper number a decision.

## The Price Rises Whether or Not Anyone Raises It

Before you take a quote from anyone, including us, go measure two numbers from a week of your own traffic: bytes per fetch, and the share of fetches that returned something you actually kept. Every quote in this post converts cleanly once you have those two, and none of them converts without them.

Then watch what happens next year. The median home page grew 7.8% in twelve months, and the pressure is all in one direction. If your bill is denominated in bytes, that's an annual price increase nobody has to announce, on a line item nobody negotiated.

At FourA we hand back what each call cost in the response itself, so the conversion is something you read as you go rather than reconstruct from an invoice at the end of the month. That won't tell you which unit to buy. It will tell you what you're actually spending per page you kept, which is the number the whole argument turns on.

---

### FourA Digest — Aug 28 to Sep 4, 2026
URL: https://foura.ai/blog/foura-digest-2026-09-04
Category: digest

## Highlights

For its whole life FourA has had one door: you send us a URL, we send you the page. This week we opened a second one, a proxy endpoint of the ordinary kind you paste into any HTTP client, with credentials you make in the Dashboard. Proxy Finder also learned to reach for a paid exit on targets that refuse everything else, and Auto got better at remembering which exits work.

## What's New

### Point any HTTP client at us

New section in the Dashboard: ACCESS, then Proxy. Create a proxy user and the page hands you the exact connection string, with curl, Python and Node examples beside it. Pick the exit type, a country, whether to keep the same exit across a run of requests, and the string rewrites itself while you choose.

Why build it when the API already works? Some jobs aren't request-and-response. A tunnel copies bytes as they arrive: no JSON envelope, no buffering. That's what a large file or a video stream needs, and our API was never going to do it.

Targeting goes deeper on the paid exits: region, city, network by ISP name, and how long an exit stays yours. Our own pool is country only, on purpose. A city inside a thinly covered country is a handful of addresses, and a filter that mostly fails is worse than no filter.

One trade, stated plainly. Through a plain tunnel your client makes the connection to the site, not us, so the work our API does on your behalf isn't in that path: the `unblocker` flag, browser-based solving, `validate` rules, session replay. The tunnel gives you our exits and our bandwidth. The API gives you what we build on top. Pick per job, not per company.

### Premium exits, and a response that says which one served you

`/api/proxy` takes an `exitClass` now, either `standard` or `premium`. Premium routes you through an exit we pay for, for the targets our own pool keeps getting the door shut on.

Send nothing and you get auto: the shared pool goes first, and a paid exit joins the search only once that search is struggling. Name a class and we obey it exactly. `standard` never escalates on its own, which is the whole point of saying it out loud.

The response carries `exitClass` back, so you always know which one delivered. A premium request our own pool answered first comes back `standard`, which is a success, not a downgrade. If your plan doesn't carry premium, the request is refused outright rather than quietly served from somewhere else.

Premium reads as a slice of your bandwidth, never as a second total: a row on Quota, a column on Metrics, a mark on the Activity row that went out that way, a tile on your Overview card. The [Playground](https://foura.ai/docs/dashboard/playground) got the control, and its empty option is load-bearing: leaving it unset sends no field at all, because "never asked" and "asked never to escalate" are different requests.

### Auto remembers what worked

Auto's ladder has always recorded which exits failed. It now records which ones delivered, from every rung rather than only the browser ones, and only after the content clears the same check that decides whether we'd hand the page back. An exit can't be marked good for a page we wouldn't return to you.

Bans age out on their own clock, too. A host's exclusion list used to have its life renewed every time a new ban landed on it; now each ban expires on the schedule it was given.

And when a run reaches your plan's browser limit, the ladder no longer stops. It works the proxy rung instead, then caches the exit that wins so later calls replay it cheaply on Single.

Auto is still the path finder, not the production route. Let it tell you which rung won and hand back the session, then point your volume at `/api/single` or `/api/browser` with that session directly. That was the [argument when Auto launched](https://foura.ai/blog/auto-endpoint) and none of this changes it.

### A page that isn't the page you asked for

Some exits sit inside a filtered corporate network where the gateway answers instead of the site. The response comes back 200, with a body, and it passed every check we had. Not any more: a page like that now counts as proof the exit is unusable rather than proof the site replied, so the request moves past it and that exit stops being preferred.

Every page shape we match on carries a size bound, so a real document that happens to quote the words can't be condemned for it. Size is a guard, never a signal. We wrote about the wider version of this two weeks ago, [when a block looks like a data point](https://foura.ai/blog/alternative-data-silent-collection-gaps).

## Under the Hood

Rate limits are now checked against your own account's ceiling before anything gets charged against shared capacity. A burst inside one account is refused on its own limit, instantly, without spending a slot anyone else is waiting on.

The in-flight number on your dashboard comes from a live gauge each instance republishes every second, not a counter that could climb and never come back down. The screen and the limiter read the same number now.

## Numbers

In our own testing, opening a tunnel to a host we'd already found exits for took 63 to 672 ms across a dozen samples, most under 260 ms. First contact with a host we've never carried is slower: seconds, sometimes tens of seconds, while the pool gets searched for exits that work on that target. That happens once per host, not once per request. Small sample, our own numbers.

Two doors means a question you didn't have last week: is this job about the bytes, or about getting through the door? Move a big file and the tunnel is the cheapest thing we own. Everything harder than that is still what the API is for.

---

### Dealer Inventory Scraping Past the Listing Sites
URL: https://foura.ai/blog/dealer-inventory-scraping-rooftop-sites
Category: use-case

Everybody builds the aggregator scraper first. Cars.com, CarGurus, AutoTrader: three sites, one parser each, and by the end of the week you've got a feed that looks like the used-car market.

Then someone asks where the rest of it is.

## The Challenge

NADA counts [16,972 franchised light-vehicle dealers](https://www.nada.org/nada/nada-data) in the United States as of its mid-2025 report, and that's before the independent lots, which nobody counts consistently. Secondary write-ups of the same NADA figure land anywhere between 15,720 and 16,990, which tells you something about how well this market is measured.

Each of those rooftops runs its own website. The inventory sitting on it is that dealer's stock, priced today, days before any of it settles onto a third-party listing site. If you're pricing used vehicles, forecasting residuals, or selling a competitive tool back to dealers, the rooftop site is the data you want. The aggregators are a lagging, filtered copy of it.

So teams go after the rooftop sites, and they find out three things in order.

They aren't unique. Almost all of them run on a small set of dealer website platforms: Dealer.com, DealerOn, Dealer Inspire, CDK, Reynolds, Sincro, Lotlinx (the exact roster depends on who's counting). Anyone selling this data builds one parser per platform, not one per dealership. Apify's [dealer website inventory scraper](https://apify.com/copious_atoll/dealer-website-inventory-scraper) says so on the tin: detect the platform first, then extract. A handful of templates covering tens of thousands of rooftops. That's the good news in this story.

The price usually isn't in the HTML you fetched. These platforms render the pricing block client-side, and payment estimates and incentives often arrive in a second call after that. A plain HTTP fetch gets you year, make, model, mileage and VIN. The price field comes back empty.

And then the part that quietly ruins datasets: on a dealer site, a failure looks exactly like a fact. An anti-bot vendor answers a suspicious request with HTTP 200 and an interstitial. A pricing block that never rendered leaves "Call for Price" in the DOM, which is also something dealers write there on purpose. Both rows land in your warehouse looking equally clean.

We covered that pattern in a different vertical, where [a block looks like a data point](/blog/alternative-data-silent-collection-gaps). Automotive is the harder version, because "no price" is a legitimate business state rather than an obvious anomaly.

## What Changes When You Split by Cost

The pipelines that hold up don't organize themselves by site. They organize by what a request costs.

The expensive request is the first one against a rooftop: the one that has to run a browser, clear whatever the dealer's platform put in front of it, and come back with a session. Everything after that is a cheap HTTP call reusing what the first one earned.

```python
import requests

FOURA = "https://api.foura.ai/api"
AUTH = {"Authorization": "Bearer pk_live_..."}

# First page of a rooftop: render it, clear the defense, keep the session.
first = requests.post(f"{FOURA}/browser", headers=AUTH, json={
    "url": "https://example-motors.com/used-inventory/index.htm",
    "unblocker": True,
    "timeout_ms": 45000,
}).json()

listings = first["body"]
jar      = "; ".join(f'{c["name"]}={c["value"]}' for c in first["cookies"])
agent    = first["userAgent"]
exit_id  = first["proxy"]     # opaque proxy ID, send it back to stay on the same exit
```

Then walk the rest of that dealer's inventory without paying for a browser again:

```python
page = requests.post(f"{FOURA}/single", headers=AUTH, json={
    "method": "GET",
    "url": "https://example-motors.com/used-inventory/index.htm?start=20",
    "proxy": exit_id,
    "headers": [["Cookie", jar], ["User-Agent", agent]],
    "validate": {
        "status": {"accept": [200]},
        "data": {
            "accept": ["vehicle-card"],
            "fail": ["Just a moment", "Access Denied"]
        }
    }
}).json()
```

Two details there carry more weight than they look like they do.

The session travels as one unit. A clearance cookie is bound to the exit that earned it and to the User-Agent it was earned under. Replay it from somewhere else, or under a different User-Agent, and the site starts you over at the challenge. That's why the jar, the agent string and the proxy ID move together. It's the detail we watch people get wrong most often: they keep the cookie, drop the exit, and then wonder why the cheap path stopped being cheap.

The `validate` block is what kills the silent-failure problem. It's the request stating what a real page looks like: accept a marker that only exists once the listing grid rendered, fail on the interstitial strings. A response that misses those rules isn't a row with a null price. It's a failure, classified as one, and [not counted as a success](/blog/validate-decides-success). In automotive, write the positive marker as well as the negative list, because "Call for Price" is genuinely ambiguous and "the vehicle card never rendered" never is.

When you don't yet know which path a given platform needs, [Auto](/blog/auto-endpoint) will find out in a single call and hand back the session that worked. Treat that as reconnaissance, not as the production route. Once you know that one platform needs the browser and its neighbours don't, pin each to the direct engine and stop paying an orchestrator to rediscover the same answer every night.

## Results

Run the arithmetic on a mid-size job (illustrative scenario based on industry benchmarks, not a specific customer): 4,000 rooftops, roughly 180 used vehicles each, refreshed nightly.

- **4,000 rendered pages instead of 720,000.** One render per rooftop opens the session; the other 716,000 pages go through the cheap path on the same session. That ratio, not the parser, is what decides whether nightly coverage is affordable.
- **Two kinds of missing price, in two different tables.** With validate rules in place, "the dealer publishes no price" and "we never got the page" stop sharing a row shape. Your model gets to see only the first one.
- **One parser per platform, not per dealership.** Detect the platform from the response, hand the HTML to the parser that owns it. A new rooftop on a covered platform costs nothing to onboard.
- **A dealer that switches platforms fails loudly.** Platform detection misses, the row never gets written, and someone gets a ticket instead of six weeks of quietly wrong prices.

Where this gets less tidy: the big dealer groups increasingly run bespoke sites off-platform, and those still need hand-built parsers with all the maintenance that implies. Rooftop freshness isn't uniform either. Some platforms cache their inventory pages hard, so "today's price" can be a day old no matter how often you collect it. If your model treats every rooftop timestamp as equally live, it's wrong in a way no amount of collection infrastructure will fix.

## Key Takeaway

The hard part of automotive data was never the three aggregators everyone benchmarks against. It's the seventeen thousand small sites that were never worth a dedicated scraper on their own and are worth a great deal together.

That shape shows up well beyond cars. Pharmacies, equipment dealers, regional grocers, franchised anything: the long tail only looks expensive while you're treating each member of it as a unique site. It usually isn't one. Get the first request right, make the session reusable, and what's left stops being a collection problem and turns into a parsing problem, which is the cheaper of the two by a wide margin.

---

### Browser Profiles: Pick What Your Requests Look Like
URL: https://foura.ai/blog/browser-profiles-per-request
Category: update

## What's New

Rotating exits is the part everyone automates. The browser signature underneath them usually never moves.

Single and Proxy Finder now take four optional fields that decide which browser your request presents: `browser`, `os`, `version`, and `profile`. The catalogue behind them is public at `GET /api/profiles` and needs no API key. Right now it holds 79 profiles across Chrome, Edge, Safari, Firefox and Tor, on Windows, macOS, Android and iOS.

And when you don't name one, Proxy Finder will change it for you. But only after a site has twice proved it doesn't want the one you sent.

## How It Works

Three of the fields are for humans and one is for machines.

`browser`, `os` and `version` narrow the catalogue, and you can send any subset of them. `os` matches on the family, so asking for `macOS` accepts every macOS release in the list, while asking for the exact release label narrows to that one. When several profiles still fit, the newest version wins, because being current is the entire point. Old majors are what blocklists key on.

```bash
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/listing/42",
    "browser": "Safari",
    "os": "iOS"
  }'
```

That resolves to the newest Safari on iOS in the catalogue, and it sends the User-Agent, the client hints and the header order that go with it, in that order. Header order is itself a signal, so nothing gets sorted on the way out.

`profile` is the fourth field: an exact id from the catalogue, for code that must keep sending the same client after a newer version lands. Proxy Finder takes all four inside its `request` object. Full parameter list is in the [API reference](https://foura.ai/docs/api/endpoints), and the [Playground](https://foura.ai/blog/dashboard-playground) reads the same catalogue, so its dropdowns can only offer what your code can ask for. The same four fields ride inside `foura_single` and `foura_proxy` on the [MCP server](https://foura.ai/mcp), so an agent can retry as another browser instead of handing back a bare 403.

Two things this deliberately refuses to do.

A combination the catalogue can't present is an error that names what's available for that browser. Falling back to a default would send a client you didn't choose and can't see in the response. A profile choice with `unblocker: false` is refused too, because the unblocker is what carries the headers ([what that flag actually does](https://foura.ai/blog/web-unblocker-chrome-headers)). Half a profile is worse than none.

The catalogue itself is measured, not typed up. A script fires every profile through the real request path and records what actually went on the wire. That matters more than it sounds: between two recent majors of one browser, the placeholder brand string changed and the brand order flipped, and that's exactly the kind of detail a detection service reads.

## Impact

Here's the part we didn't expect.

A default is a shared default. The client your request presents when you ask for nothing is the one that every request which asked for nothing presents, and a defense that wants to key on something cheap keys on exactly that. It fails in a way that looks like nothing else, too: a site that refuses one browser refuses it at every exit you own. You spend the whole retry budget proving the same client is unwelcome.

We measured it three times, on three vendors, and it was the same shape each time.

A property portal behind PerimeterX turned down nine attempts on the default. Changing only the platform the request claims (same everything else, same pool) returned the page six times out of six. A supplements retailer behind Akamai refused the default and served two other browser families without complaint. A financial news site behind DataDome answered the default with a 401 and a 774-byte interstitial, while three other profiles pulled the real page, about 760 KB of it, twelve times each. We ran that one forward and backward to be sure the order wasn't doing the work.

So Proxy Finder rotates the browser family now, not just the exit. Two independent exits have to refuse before it moves, because one refusal is one exit's opinion. Then it steps along a ladder that starts with the smallest possible change, the platform, and only then tries other families.

It costs nothing. The rotation changes what a retry sends, never whether a retry happens, so requests and credits per task come out exactly where they were.

## For Power Users

The rotation stays out of your way, and the rules for that are worth knowing.

It never fires when you named a profile yourself. It also never fires when you sent your own `user-agent` or `cookie` header, and that one is the important one: a clearance cookie is bound to the client that earned it, so rotating the signature underneath a working session replay would break a request that was succeeding. Pin what you want and it stays pinned.

Not every failure counts as evidence for moving the profile, either. A recognised defense vendor counts. So does a bare refusal status (401, 403, 429, 503) with no vendor named, and that one turned out to matter. One task came back with eight status rejections and nothing recognised on any of them: real refusals the rotation was ignoring, because it trusted only the detector. A missing page or a country block doesn't count. Those are answers about your URL and your geography, not about your client.

You can see all of it. A successful Proxy Finder response carries `profile` only when we chose it, never when you did. A failed task carries `attemptReport.profilesTried`: the families it sent, in first-use order, with `default` for a request that went out untouched. Without that field, "we tried four browsers and every one was refused" and "we never changed the browser" look identical from outside.

One habit worth stealing: when you're testing whether a profile helps, hold everything else still. Scrapfly's [2026 rundown of fingerprint testing tools](https://scrapfly.io/blog/posts/best-browser-fingerprint-testing-tools) puts it well, that changing three variables between runs tells you something worked but not which change mattered. Same target, same exit, one field different. That's also how every number above was produced.

## What's Next

The candidate ladder only grows by measurement, one target at a time. A family gets added after we've watched it open a target the default couldn't, not because it looked like a good guess, and the catalogue gets re-measured on every engine bump rather than carried forward.

That's the uncomfortable shape of this problem. The best client signature is a moving target, tracking it is ongoing work rather than a thing you ship once, and whatever won last quarter is on somebody's list by now. Which is why it's a field you set and a catalogue you can read, instead of a number we picked for you.

---

### FourA Digest — Aug 21 to Aug 28, 2026
URL: https://foura.ai/blog/foura-digest-2026-08-28
Category: digest

## Highlights

Usage now counts every hour your billing period touches, so the credit total on your Usage & Limits page covers the period from its first second. Organizations got the follow-through they were missing last week: the person you add hears about it, so does the owner whose plan pays, and the role picker finally says what a role can do. And we went through the Dashboard and rewrote the messages that were written for us rather than for you.

## What's New

### Every hour in your period counts

Your billing period starts at the second you signed up. Usage gets measured in fixed buckets. Those two things almost never line up, so the arithmetic mapping one onto the other has to be exact at the edges.

It is now. A period gets broken into whole buckets of the finest resolution still available for each part, nothing split, nothing counted twice. All three places that read usage share one implementation, which is the actual fix. Three copies of the same arithmetic is how one of them gets to be wrong.

What you'll notice: every number on Usage & Limits reads a little higher than it did last week. Same traffic, fuller count. Nobody is pushed over a plan limit by the change. The same arithmetic gates your quota, so it mattered in both directions.

### Nobody joins an organization in silence

[Organizations landed last week](https://foura.ai/blog/foura-digest-2026-08-21) and you could add a colleague, hand them a role, and let them use keys the company pays for. What you couldn't do was tell them. The hint under the form said to go do that yourself.

Two emails now. The person added gets one naming the organization, who added them, what their role can do, and where to leave it if they weren't expecting any of this. The owner gets one when somebody joins, because the organization's keys bill against the owner's plan and one more person spending their credits is their business, not a courtesy. Neither mail goes to whoever pressed the button. You don't need a receipt for your own action.

The owner's notification fires on both paths: somebody added directly, and an invitation taken up at first sign-in, where there's no actor at all because the person let themselves in.

Roles explain themselves too. A line under the picker changes as you choose, and the Role column carries a tooltip covering all three including owner. Choosing between "Member" and "Admin" with no idea what either one can do is how people hand out admin by default.

### One step to add a colleague

Type an email address, press Add. If they already use FourA they join right away. If they don't, we mail them an invitation and they're in the moment they sign in. Same button, same confirmation, same answer either way, and the page describes both outcomes in one sentence instead of naming which one applies to the address you typed.

That second dialog is gone, and so is the reply that used to tell you whether an address already had an account here. Whether some arbitrary email is registered with us isn't a question we answer.

### The Dashboard stopped writing to the log

"Failed to fetch organizations" is a line for us. It was showing up in front of you.

Thirty-five of those became sentences a person can act on, like "We couldn't load your organizations. Try again in a moment." Contractions everywhere a human reads. "Invalid member id" and its siblings now say what went wrong instead of naming a variable. The console lines they used to be confused with are untouched, because those really are for us. So is the API-shape validation you get back when you're calling us from code, and so are the machine-readable codes the Dashboard branches on.

Emails got the same pass. An invitation asking a stranger to join "an organization" is the mail people bin, so the names of things you chose are back: the account, the key, the organization, whoever invited you. Free-form text a customer typed still stays out of every mail we send.

## Under the Hood

Browser was leaking one file handle per rendering session, and it wasn't our code doing it. An upstream dependency closes one of its two log handles, then returns early and skips the second, but only when the caller supplies its own profile directory. We supply one on every launch, which made the leak both guaranteed and permanent.

The patch wraps that single method rather than forking the dependency. It runs the original first and only acts if the handle is still open, so the day upstream moves that line above the return, our patch quietly becomes a no-op. The tests reproduce the leak before the patch gets installed, so the file states what it's defending against rather than just asserting that things are fine.

Practical effect: long-running Browser instances hold their capacity instead of thinning out as sessions accumulate. If you want to control what those sessions look like on the wire, [browser profiles](https://foura.ai/blog/browser-profiles-per-request) shipped alongside this.

Both of the fixes above started in the same place. Something passed a check that wasn't the check that mattered: a green test suite while an hour went missing from every period, a process reporting for duty while it had run out of the one resource it needed. Green is easy to get. The harder question is what your instruments would have to see before they'd go red, and whether they can see it at all.

---

### Search, Agent, Training: The Web's New Bot Rules
URL: https://foura.ai/blog/search-agent-training-bot-rules
Category: insight

## The Web Is Sorting Bots by Purpose, Not by Behavior

Every anti-bot system built in the last fifteen years asks one question: does this traffic look automated? Header order, wire-level fingerprints, mouse movement, session timing. All of it tries to infer something about the client from the shape of the request.

On July 1, 2026, Cloudflare [changed the question](https://developers.cloudflare.com/changelog/post/2026-07-01-ai-traffic-options/). Bot traffic now sorts into three categories that have nothing to do with what a request looks like on the wire. Search covers "crawlers that index your content so they can answer questions about it later." Agent covers "automated activity acting in real time on a person's behalf." Training covers "crawlers that take your content to train or fine-tune a model."

Picture three requests arriving at the same server. Same client, same headers, same timing, identical down to the byte. Under this model they can get three different verdicts, decided entirely by what you plan to do with the page after it arrives.

That's not a better detector. It's a different primitive.

### The September 15 Deadline Is Narrower Than the Panic

The version of this story going around [developer forums](https://www.reddit.com/r/AI_Agents/comments/1umfd6q/cloudflare_is_about_to_block_ai_agents_by_default/) is that Cloudflare blocks AI agents across a fifth of the web on September 15.

The changelog says something much smaller. The new defaults apply to "new domains onboarding to Cloudflare." On those domains, "bots classified as Training or as Agent are blocked on pages that display ads, while Search remains allowed." Everyone already on Cloudflare chooses their own setting, and can do it any time before the date.

So: new domains only, ad-supported pages only, and one of the three categories still gets through by default. That's a real change and it isn't a wall across the internet.

But the narrow scope is the interesting part. Cloudflare didn't publish a policy, it published a *default*, and defaults are how a policy becomes the norm without anyone voting on it. The number worth watching isn't September 15. It's how many of those domains never touch the setting afterward.

**What this means:** if you collect data, the useful question stopped being "can I get through this site's protection" and started being "which category does this site think I'm in." Those have different answers and only one of them is something you can test for.

### Purpose Can't Be Measured. It Has to Be Declared.

Here's the mechanical problem with sorting traffic by intent: intent isn't in the packet.

A fingerprint can be measured. Mouse movement can be measured. "Why are you fetching this page" can't, so the system needs the client to say it out loud, and it needs a reason to believe the answer. That's the job Web Bot Auth does. The agent signs its requests with a private key, publishes a key directory, and the edge verifies the signature against it, built on [RFC 9421 HTTP Message Signatures](https://datatracker.ietf.org/doc/html/rfc9421). Cloudflare's docs set the bar for a verified bot as "honest self-identification."

Now look at what's enforcing this at scale. The spec is [draft-meunier-webbotauth-httpsig-protocol-02](https://datatracker.ietf.org/doc/draft-meunier-webbotauth-httpsig-protocol/), last revised August 18, 2026. Intended status: Standards Track. Actual status: an "Active Internet-Draft (individual)" that's "not endorsed by the IETF" and carries "no formal standing in the IETF standards process." It has two authors. One works at Cloudflare, one works at Google.

We think the design is right, and that's worth saying before the criticism lands. Signed identity beats the captcha arms race for anyone who intends to behave. A crawler that identifies itself can be allowed, throttled, or billed on purpose instead of guessed at, and site owners get a control that doesn't take out real visitors as collateral. Set that against a decade of blocking IP ranges and hoping.

What it can't do is stop anybody. A system built on declared purpose only sorts the traffic that declares itself. Everything else falls back to the detection stack that was already there, and that stack keeps getting sharper: Cloudflare's [session-scoped behavioral scoring](/blog/cloudflare-precursor-session-fingerprint) shipped twelve days after the new categories did.

So the two aren't competing. Identity sorts the honest, detection handles everyone else, and the second one is where your traffic lands by default if you never declare anything.

### There's No Box for Collecting Public Data

Now the part that should bother anyone running a collection pipeline.

Take the work we've published this year. A [timber price index](/blog/korena-timber-index) built from public listings. [MAP violation detection across six marketplaces](/blog/detecting-map-violations-across-marketplaces), which means fetching the same product page from six different vantage points and comparing what each one says. [App store rankings and review sentiment](/blog/app-store-intelligence-at-scale). [Ad placement checks run from the country the campaign was actually bought in](/blog/ad-verification-geo-authenticity).

Sort those into Search, Agent, or Training.

Search doesn't fit: Cloudflare's own definition attaches an expectation of "referral traffic or other equitable compensation in return," and a nightly price check sends referrals to nobody. Agent doesn't fit either, because no human is sitting in front of a screen waiting on that fetch. And Training is plainly wrong, since nothing gets absorbed into a model.

This is a taxonomy written to describe the AI traffic that showed up in the last three years, now applied to a business that predates it by a decade. Price intelligence, alternative data, SERP tracking, brand protection, ad verification, compliance monitoring: none of it is new, none of it is agentic, and none of it has a box to check.

Traffic with no box gets sorted by whoever drew the boxes. Usually into the nearest one.

## What This Means for Data Teams

Four things worth doing while the rules are still soft.

**Decide which category you'd honestly claim.** Not the one that gets you through the door. The one you'd defend in writing if a publisher asked you directly. If the honest answer is "none of these," then you're in the group with the most to lose when the taxonomy hardens, and the most to gain from saying so while there's still an argument to be had.

**Read the target's settings, not the headlines.** A site's bot policy is now a property of that site, configurable per path, and it changes without notice. Treating "Cloudflare blocks agents in September" as a fact about your pipeline will send you rebuilding things that were never at risk.

**Assume the ad-page test spreads.** Cloudflare tied its default to pages that display ads, a decent proxy for "this page earns money from human attention." That line will move, and Cloudflare isn't the only one drawing it. AWS WAF shipped [AI traffic monetization](https://aws.amazon.com/blogs/aws/aws-waf-adds-ai-traffic-monetization-capability-to-help-content-owners-charge-ai-bots-for-content-access/) on June 15, 2026, answering with a 402 and machine-readable payment terms. Akamai took the partnership route with TollBit and Skyfire. Three of the largest edge providers now sell the same control surface, which we looked at from the pricing side [when pay-per-crawl launched](/blog/pay-per-crawl-splits-the-web).

**Keep your collection able to work in either lane.** The identified lane (sign, declare, get allowed or get billed) and the unidentified one (get judged on behavior, like always) are going to coexist for years. Building as though only one of them exists is the expensive mistake here, in both directions.

## The Boxes Are Going to Be Redrawn

A prediction we're happy to be held to: a fourth category shows up within a year.

The first version of any taxonomy gets written by whoever's under pressure, and the people being classified aren't in the room when it happens. Search, Agent and Training describe what AI companies do to publishers. They don't describe a market research firm, a compliance team, or a retailer checking a competitor's shelf price, and those three have been fetching public pages politely since before "agent" meant anything in this context.

The fight over what that fourth box is called, and who gets to check it, will matter more to the data industry than any anti-bot benchmark published this year. That one's worth showing up for.

Because the fallback is simple enough. If your traffic can't name itself, somebody else will name it for you.

---

### FourA Digest — Aug 14 to Aug 21, 2026
URL: https://foura.ai/blog/foura-digest-2026-08-21
Category: digest

## Highlights

An organization used to be a row that could only ever hold one person. Now it's a page you run: invite a colleague, hand them a role, let them create keys the company pays for. Proxy Finder also stopped answering "out of tries" and started naming the wall it hit, and Browser spent the week making sure it tells a page the same story twice.

## What's New

### Organizations you can actually run

Adding a colleague used to mean emailing us, so teams bought two unrelated subscriptions.

Your organization has its own page in the Dashboard now, with three roles behind it. The owner carries the subscription its keys bill against, so there's exactly one and ownership moves by transfer. Admins handle usage, billing and members. Members use the thing. Invitations go by email address and work for someone who's never signed up.

Anyone in an organization can create keys it owns and move a personal key into it, so a developer doesn't need a personal key that bills them for company work. Usage on an org key bills the owner's plan, and every confirmation says whose plan pays. Any member can rename a key; regenerating, disabling and deleting stay with owners and admins, since those stop every colleague using it the instant they happen.

One Owner filter runs across Overview, Detailed Metrics, Recent Activity and your key list. Usage & Limits and Billing stay personal, since a member has no business reading the owner's quota.

### Proxy Finder stops guessing

"Download maxTry limit reached" read the same whether every exit was blocked, every exit was dead, or we fetched the genuine page and your own rule threw it away. Those three need opposite fixes.

A failed task now carries `attemptReport`: how many exits never answered, how many a recognised defense refused and which vendors did it, how many your `validate.status` rejected, and how many returned HTTP 200 with no defense in sight and failed only your `validate.data`. A plain summary sentence comes with it.

But that last count is the one worth having. A content rule that can't match looks exactly like being blocked from every angle we used to measure, and no retry will ever fix it. (More on how [validate rules decide success](https://foura.ai/blog/validate-decides-success).)

So the other half is the profile. Proxy Finder rotated exits and never the client signature, so a site refusing one browser profile refused it at every exit in the pool. A refusal moves the profile now, on a retry that was already going to happen, so requests and credits per task don't change. Pin `profile` yourself and nothing changes. On the hardest targets, mind you, the exit you land on still matters more than the profile you send.

### Browser stops contradicting itself

Asking Browser for a User-Agent used to be worse than not asking. Three layers each had their own idea of who the request was, so one request could claim Windows, a Mac and a version the fleet wasn't running, all at once. One value now, decided once, carried everywhere: the launch, the page, the workers the page starts.

Client hints are derived from that string, so `sec-ch-ua`, the platform and `navigator.platform` agree with it. The response reports back the string we actually sent, which matters because clearance cookies are bound to the exit and the User-Agent together. The renderer question also answers the same way in the document and in a worker now, one more of the [weak signals that add up](https://foura.ai/blog/headless-browsers-leak-more-2026).

Three more landed with it:

- **The clock follows the exit.** Browser runs in the timezone of the country your exit sits in, so a page rendering local times shows what a visitor from there would see. When the country isn't known, the clock is left alone.
- **WebRTC stays on the same path as everything else.** A proxy setting covers what a browser sends over TCP. WebRTC isn't on that path, so a page asking it for ICE candidates gets a separate answer. Browser switches that off whenever a request carries an exit.
- **Anchored URLs cost what they should.** A URL ending in `#reviews` used to run the clock out every time. It's back at normal speed.

### Cheaper routes, and a Dashboard that counts straight

Imperva injects its script into healthy pages, not only its block pages, and [Auto](https://foura.ai/blog/auto-endpoint) couldn't tell the two apart, so healthy pages escalated to a browser for nothing. On a car rental site that was 75 credits and 27.5 seconds across six attempts; it's one attempt now, 10 credits, about six and a half seconds. Some sites hand you a session inside the refusal they answer a session-less request with, and all four engines now send it straight back before escalating.

The Overview credits card showed everything spent and labelled it billed. Under pay-for-success those differ, and the gap is real money, so both are on the card: billed as the number, spent underneath, per product and in total. The Requests card splits the same way. Period and detail are separate controls too, from 30 minutes to a year plus a custom range, retiring the pill that read "1D" and opened thirty days.

In the [Playground](https://foura.ai/blog/dashboard-playground), the carry button now offers the profile from the last response, so a request that went out under a profile you didn't type replays the version that worked. Every parameter is in the [API reference](https://foura.ai/docs/api/endpoints).

## Under the Hood

Proxy Finder keeps more history per host: 32 exits instead of a dozen. On a live A/B it was level on easy targets and better on hard ones, where median time to a page went from 5.5s to 3.8s while fleet-wide latency didn't move. One target went the other way and we don't know why yet, so it gets its own measurement.

A task that's going to fail will fail either way. The difference is whether you close the ticket in a minute or spend the afternoon measuring the wrong thing.

---

### Alternative Data: When a Block Looks Like a Data Point
URL: https://foura.ai/blog/alternative-data-silent-collection-gaps
Category: use-case

A retailer's product page answered with status 200 and nothing in it. The pipeline didn't log a block. It logged an empty shelf.

That's the failure nobody budgets for in alternative data. Not a missing dataset, not a slow vendor. A collection layer that keeps handing you rows while quietly measuring something other than the company you're covering.

## The Challenge

In January 2026, Exabel surveyed 100 fundamental portfolio managers and analysts across the US, UK, Singapore and Hong Kong, managing roughly $610 billion between them. [71% named combining data from different sources as the most frustrating part of working with alternative data](https://www.exabel.com/blog/2026-alternative-data-market-report-out-now/), and 94% said they already run AI or machine learning somewhere in their research process.

Read those two numbers next to each other and the shape of the problem shows up. The modeling side is well staffed. The plumbing underneath it isn't.

A web-collected panel (prices, stock status, careers pages, review counts, marketplace assortment) is a time series before it's anything else. Every time series carries an assumption that nobody writes into the spec: today's observation was collected the same way yesterday's was. Break that assumption loudly and you get an alert. Break it quietly and you get a signal.

Three of those quiet breaks show up in almost every web-collected panel.

**The 200 that isn't content.** Bot defenses stopped answering with a clean 403 a long time ago. A challenge page, a consent wall, or an empty-results template arrives with a success status and a body your parser reads as zero results. Fewer listings looks identical to less demand.

**The vantage point moved.** Price, currency, assortment, promotional banner, sometimes whether the page renders at all: retailers decide all of it from where the request appears to come from. If Monday's collection exited in Germany and Thursday's exited in Poland, there's a step in your series that belongs to you, not to the retailer.

**The rotation that took the first answer it got.** Rotate through exits without telling the collector what success means, and it stops at the first exit that responds. A refusal is a response. So the row lands, the job goes green, and nobody looks again.

None of these throw an exception. Ingestion counts rows, the dashboard stays green, and the analyst gets a chart. Then the model spends a quarter learning the behavior of your collection infrastructure instead of the behavior of the business.

## The Approach

Treat data integrity as a property of the request, not of the parser downstream. Three things have to be true.

**1. Say what a real page looks like.** The collector has no way to work it out on its own. Give it a string that only genuine content carries and a couple that only refusals carry, and a challenge page stops counting as an observation. We wrote about this when [validate rules landed](/blog/validate-decides-success): the request itself decides what success means.

```python
import requests

r = requests.post(
    "https://api.foura.ai/api/proxy",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "maxTries": 8,
        "exitCountries": ["DE"],
        "request": {
            "method": "GET",
            "url": "https://retailer.example/p/12345",
            "validate": {
                "status": {"accept": [200]},
                "data": {
                    "accept": ["data-testid=\"price\""],
                    "fail": ["Access Denied", "Just a moment"]
                }
            }
        }
    }
).json()

observation = r["data"]        # content your rules accepted, or nothing
exit_id = r["proxy"]           # opaque ID of the exit that delivered it
served_from = r["exitCountry"] # verify it against what you asked for
```

Rotation now has a definition of done. It keeps trying exits until one returns something that passes your rules, instead of returning the first page-shaped object it meets.

**2. Hold the vantage point still.** `exitCountries` is a strict allowlist of target-visible country codes, and exits with unknown geography are left out rather than substituted. Two honest caveats, both worth knowing before you build on it. Country metadata is refreshed on a cycle (normally within about ten minutes), so it isn't a live lookup at request time, which is exactly why the response carries `exitCountry` for you to check. And when the pool has no match for the scope you asked for, the call comes back with HTTP 200 and an error envelope rather than an exception. Read the body, not the status. Preserve the scope and retry later instead of widening it, because a widened scope is a break in the series.

**3. Keep the identity of the exit.** The `proxy` field is an opaque ID, not an address. Pass it back on a follow-up Single or Browser call and the detail page comes from the same vantage point as the search page that found it ([how to reuse an exit](/docs/how-to/reuse-a-proxy)). Store that ID and the `X-FourA-Request-Id` header alongside every row. When an analyst questions a spike six weeks later, the question "was this real?" becomes a lookup instead of an argument.

For a source you're onboarding and don't understand yet, [Auto](/blog/auto-endpoint) is the fastest way to find a working path: it walks the cheap-to-expensive ladder, tells you which rung won, and hands back the session that worked. Use it to find the route, then put production volume on the direct engines. Replay that session through Single where nothing needs rendering, Browser where it genuinely does. Path finding and steady-state collection are different jobs.

## Results

What changes when those three properties hold, on a panel of a few thousand product pages a day across a dozen retailers (illustrative scenario based on industry benchmarks):

- **A gap is a gap, not a guess.** Refusals never enter the panel as zeros, so an empty result set means the retailer showed nothing, and your absence signal is worth trading on.
- **Comparable rows.** Every observation in a series comes from the country the series is defined in, so a price move is a price move.
- **Reproducible history.** Exit ID plus request ID per row means any disputed data point can be traced back to the exact call that produced it.
- **Cheaper per usable row.** Requests that would have produced a discarded observation get retried at collection time rather than paid for, parsed, stored, and later cleaned out of a backtest.

But the last one is what research teams underrate. A bad row isn't free just because it was cheap to fetch. It costs a research cycle, and sometimes it costs the confidence of the person who has to sign off on the signal.

## Key Takeaway

Alt data buyers evaluate providers on coverage, latency, and history depth. Almost nobody asks the question that decides whether a panel is tradeable: how does this dataset behave on the day the source refuses to answer?

A vendor that drops the row is honest. A vendor that returns a courtesy page as an observation has sold you a measurement of their own infrastructure, and you'll pay for it in a backtest that works right up until it doesn't. That question belongs in every data diligence checklist, and it belongs in your own pipeline first, because if you're collecting it yourself, you're the vendor.

---

### FourA Digest — Aug 7 to Aug 14, 2026
URL: https://foura.ai/blog/foura-digest-2026-08-14
Category: digest

## Highlights

Plenty of sites hand their front page to anyone and lock everything one click deeper. Auto walks in the front door now: it takes the session that entry page gives out, then asks for the page you wanted while carrying it. Browser got the heavier work this week. It clears Cloudflare's checkbox challenge when several requests hit the same page at once, and when a page stays shut it reports what it saw instead of one flat word.

## What's New

### Auto opens pages that gate behind a session

An eBay listing refuses a cold request on every route we have. The same URL opens when the request carries the cookie jar eBay's own entry page hands to any visitor. No login, no borrowed account, nothing you couldn't do by hand in a tab.

Auto does it for you now. When an exit reaches the origin and still gets refused the deep page, Auto fetches the site root through that same exit, keeps whatever cookies come back, and asks again. The response tells you it happened: the winning rung reads `warmup`.

But cost is the interesting part. That session comes back portable, so the jar isn't welded to the exit that earned it. Follow-up reads replay through `/api/proxy` and land on `/api/single` at 2 credits. It's the same escalate-then-replay chain we [wrote about for Cloudflare clearance](https://foura.ai/blog/cloudflare-precursor-session-fingerprint), with a vendor's own session cookies standing in for `cf_clearance`.

Bounded on purpose: two tries per request, on different exits, only after the deep URL has already failed, and only when the exit reached the origin in the first place. So a site that simply blocks us pays two extra sub-calls once, not a loop. More on how the ladder picks its rungs in [the Auto write-up](https://foura.ai/blog/auto-endpoint).

### Browser clears checkbox challenges when requests overlap

Browser now solves Cloudflare's checkbox widget on concurrent requests to the same page. Three at once on a news site behind Turnstile: 5.2s, 5.8s, 9.1s.

Two smaller changes rode along. A press counts only once the widget is actually gone, because Cloudflare re-issues its challenge more often than you'd expect (the first press is regularly not the end of the conversation). And a page that clears reports `defenseSolved: true` on the call that cleared it, which is the same call billed for the solve.

### A blocked page tells you what the solver saw

"Timeout" points you at latency. Most of the time latency isn't the problem and the answer is one exit over.

When Cloudflare rejects a solve it re-issues the challenge and drops its own retry marker into the jar. Browser reads that marker. Rather than waiting out the clock, it answers in around 17 seconds, naming the vendor, the presses it made and whether clearance was granted:

```
Timeout after 12s: the cloudflare challenge did not complete from this exit
(2 checkbox presses, clearance granted, challenge re-issued by the site)
```

One of those lines tells you to send the request out a different way. The other tells you nothing.

Errors from the API layer read straighter too. A request that outlives the wait comes back as a timeout, a service we can't reach comes back as unavailable, and neither is described as a proxy problem when the request carried no proxy at all. `timeout_ms` on a Browser call is honoured to the full 120 seconds the API accepts, so a slow target gets the budget you set and you read the engine's own verdict rather than the gateway's. Parameters are listed in the [API reference](https://foura.ai/docs/api/endpoints).

### Billing details, and correcting an invoice in its issue month

Bulgarian invoices print a company representative (MOL) in the recipient box. Nothing in the system collected it, so that line could only ever come out empty. Billing details has the field now.

The Invoices table also offers Update details on an invoice that's still inside its issue month and whose frozen details differ from your current billing profile. The dialog names each field that changes and what it changes to, says plainly that the number, the dates and the amounts stay where they are, and confirming it is your consent, recorded on our side. An invoice in the window with nothing to change reads "Editable until" and its date, so the window is something you can see rather than something you find out about later.

## Under the Hood

Every script the Dashboard runs is served from our own origin, and signing in returns you only to a path on this site.

Rollouts of the rendering service go one server at a time, and each server has to serve a real page before the next one is touched.

On the status portal, the issues endpoint serves open and resolved items over its public API, matching what the page lists.

A refusal that names itself is one call. A wait that ends in "Timeout" is a guess about what to try next, paid for at the same price. Errors are a product surface, and this week we started treating them like one.

---

### Web Scraping Is Consolidating. Here's What Changes.
URL: https://foura.ai/blog/web-scraping-consolidation
Category: insight

## The Independent Web Scraping Vendor Is Getting Smaller

On July 9, 2026, [Oxylabs announced a $130 million investment from Warburg Pincus at a $3.6 billion valuation](https://warburgpincus.com/2026/07/09/oxylabs-announces-130-million-investment-from-warburg-pincus/). Their portfolio already included Webshare (acquired 2022) and [ScrapingBee](https://www.scrapingbee.com/blog/scrapingbee-acquisition/) (acquired 2025). That's not a coincidence. It's the shape of the market now.

The mid-market web scraping API is disappearing. Not one vendor at a time. All at once.

Three years ago you had a dozen credible options between the enterprise floor (Bright Data, Zyte) and the hobbyist ceiling (a shell script and a proxy list from GitHub). Today most of the names in the middle have either been bought or reshaped their pitch to court a different buyer. The pattern is consistent enough that "who owns this vendor in 18 months" now belongs on the same evaluation checklist as uptime and success rate.

Here's what's actually happening, and what to ask about it.

### The Consolidation Pattern

The data infrastructure category, [pegged at $1.17 billion in 2026 and projected to reach $2.23 billion by 2031](https://www.mordorintelligence.com/industry-reports/web-scraping-market), is growing fast enough to attract private-equity capital but small enough that a $130M round can rewire it. The public framing around the Oxylabs deal makes the intent clear: capital for AI-agent-era product development, with room for more acquisitions. Translation: expect two to four more mid-market deals before the year is out.

Oxylabs isn't alone. [Bright Data reports over $300M in annualized revenue and 50% year-over-year growth](https://brightdata.com/blog/general/data-for-ai-is-fueling-massive-growth-at-bright-data), driven mostly by data-for-AI demand. Zyte is [publishing free industry whitepapers](https://www.zyte.com/whitepaper-ebook/2026-web-scraping-industry-report/) and positioning itself as the compliant-by-default option upmarket. Firecrawl has quietly shipped official SDKs in six languages (Python, Node.js, Go, Rust, Java, Elixir) plus a CLI, [pitching itself as "the web data API for AI agents"](https://www.firecrawl.dev/). None of these are neutral moves. Each one is a claim on a specific buyer segment.

What the buyer sees is fewer nouns in the same category. What the buyer doesn't see (and this matters more) is the change in incentives when a formerly independent product becomes a line item inside a larger portfolio.

### What You Lose When Your Vendor Gets Acquired

The best case: nothing changes for a year, the founders leave quietly, the roadmap re-prioritizes around the parent's customer segment, and one morning you find out your pricing tier is being sunset.

The realistic case: pricing gets restructured toward enterprise. Response time on niche bugs slows because the specialists you used to email now have three products to look after. The docs stop referencing the old product name in half the places. And your account manager, if you had one, changes twice in six months.

We don't say this to trash the acquiring companies. Oxylabs' post-acquisition pitch for ScrapingBee is coherent and their engineering bench is deep. But if you bought ScrapingBee originally because you wanted the simplest possible API and no enterprise sales motion, the thing you actually bought was the independence, not the endpoint. When the endpoint stays and the independence goes, you kept the wrapper and lost the reason.

The same logic applies to any acquisition. You signed up for a set of tradeoffs the founders were willing to defend. New owners come with new tradeoffs. Sometimes better ones. Rarely the same ones.

### The Full-Stack Pitch and Its Cost

The other consolidation story is vertical, not horizontal. Every serious player is racing to become a "full-stack platform" that bundles proxies, requests, browser rendering, AI extraction, dashboards, and MCP integration under one contract.

Browserless' [State of Web Scraping 2026](https://www.browserless.io/blog/state-of-web-scraping-2026) predicts this continues: "the market will also continue consolidating as platforms expand into full-stack solutions, giving teams fewer fragmented tools to piece together." That framing is generous to the vendors. From the buyer's side, one contract also means one price schedule, one bug queue, one place to be down when something goes wrong, and one negotiation partner who now knows exactly how much of your infrastructure they own.

Full-stack has real advantages. Consistency of billing. Fewer integration seams. A single throat to choke when things go wrong. But it changes the answer to a specific question: when a small piece of the stack falls behind the state of the art, do you still have the option to swap that piece out? Full-stack platforms tend to say yes and then quietly discourage you from doing it.

## How to Evaluate Vendors in the Consolidation Era

The old evaluation checklist was mostly technical: success rate, latency, proxy pool size, unit price. Those still matter, but they're the easy part. The hard part is now about intent.

Ask the vendor these five questions before you sign anything:

- **Who owns the roadmap in 18 months?** If the answer includes "we can't say" or "our parent decides," you have your answer.
- **What were your last three pricing changes, and who did they help?** A vendor that keeps changing tier names and quietly retiring the cheap plans is telling you which customer segment they actually want.
- **Show me a bug fix from last month for a customer under $1,000/month.** This filters for support quality on customers who aren't the important ones.
- **What's your capital source, and what's it optimized for?** PE-backed means growth to exit. Founder-owned means growth to independence. Both are legitimate. They're not the same.
- **If we outgrow you, or if you get acquired, how do we leave?** A vendor confident in the relationship will answer directly. A vendor uncomfortable with the question is telling you something.

None of these are trick questions. They just filter for whether you're buying a product or a portfolio.

Two related pieces we've published are worth reading alongside these: [why proxy pool size stopped mattering in 2026](https://foura.ai/blog/proxy-pool-size-stopped-mattering) covers the vendor-marketing side of the same story, and [the state of web data collection in 2026](https://foura.ai/blog/the-state-of-web-data-collection-in-2026) sets the broader context we're working from.

## What Comes Next

The mid-market will keep thinning through 2026 and into 2027. At least two of the current tier-2 API-first vendors will be acquired or wind down. The buyer who bought the "independent, developer-first, no-enterprise-motion" pitch in 2024 will need to make that choice again by 2027, from a smaller menu.

The upside: the vendors who stay independent through this cycle will be doing it on purpose. That's a signal worth paying attention to. Ask them why they didn't sell. If the answer is "we didn't need to," you probably found what you were looking for.

We build web data infrastructure at [FourA](https://foura.ai). We're not going anywhere, and we didn't need $130 million to say that.

---