# Response Headers

> URL: https://foura.ai/docs/api/response-headers
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

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, except a body FourA can't read at all (`400 Invalid JSON in request body`, `413`), which is refused before an ID is assigned | 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) and the 503 `API key check temporarily unavailable` | Seconds to wait, as an integer. Matches `retry_after_seconds` in a plan-limit body and `retryAfter` on the 503. |
| `X-FourA-Exit-Class` | Every `/api/proxy/` or `/api/auto/` call that named an `exitClass` and delivered a page, and every Single or Browser call served through a premium exit | `premium` or `standard`: the class of exit that delivered the body. A failed Proxy call delivered nothing and carries none. |
| `X-FourA-Browser-Used-Today` | Every `POST /api/browser/` answer your plan's limits didn't refuse, and every `POST /api/auto/` answer whose ladder sent a request they didn't refuse | Browser requests counted today on your account: see below. |
| `X-FourA-Browser-Limit-Per-Day` | The same answers, when your plan sets a daily number | Browser requests your plan allows per day. |
| `X-FourA-Check-Page` | Single, Proxy Finder and Browser responses whose HTTP 200 body is a bot-check or refusal page FourA recognises | The page's name, for example `amazon-captcha`. Such a request isn't billed: see [Request Outcomes](https://foura.ai/docs/api/outcomes). |
| `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](https://foura.ai/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](https://foura.ai/docs/api/outcomes) for which outcomes are billable).

### Cost reference

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

`/api/auto/` is one request on your dashboard, with a credit cost that 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. On Auto, the body's `meta.credits` holds the same number. Single, Proxy and Browser bodies don't carry it, so on those responses the header is the only place to read it. Each call's [Activity](https://foura.ai/docs/dashboard/activity-log) row shows it too.

## 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](https://foura.ai/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/` or `POST /api/auto/` response that delivered a page whenever the request named an `exitClass`, where the body carries the same value (`exitClass` on Proxy, `meta.exitClass` on Auto), and on a Single or Browser response whenever the `proxy` you pinned was a premium exit, where the body has no field for it. A failed Proxy or Auto call served nothing, so it carries neither the header nor the field.

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

Traffic through a premium exit counts toward your premium traffic as well as your total bandwidth. It's measured on the network and includes premium attempts that didn't return your page, so a request answered with `standard` can still have used some premium traffic, on an attempt that failed before the standard pool answered. This header names the class that delivered, not whether premium traffic was used: the **premium** mark on an [Activity](https://foura.ai/docs/dashboard/activity-log) row and the [Usage & Limits](https://foura.ai/docs/dashboard/quota) page show what was counted. What `exitClass` does and when a premium exit is used: [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

## X-FourA-Browser-Used-Today and X-FourA-Browser-Limit-Per-Day

These two headers carry your daily browser allowance on the answer itself, the same numbers the [Usage & Limits](https://foura.ai/docs/dashboard/quota) page shows, so you can follow it without polling the dashboard.

```
HTTP/1.1 200 OK
X-FourA-Browser-Used-Today: 1250
X-FourA-Browser-Limit-Per-Day: 5000
X-FourA-Credits: 47
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json
```

The count starts again at midnight UTC and covers every key on your plan, not only the one that made this call. A request that your plan's limits refused carries neither header: its body has `used_today` and `limit_per_day` instead, see [Rate Limits](https://foura.ai/docs/api/rate-limits).

On `POST /api/browser/` the count includes the request you're reading. On `POST /api/auto/` it's the highest count the ladder was given while it ran, so it can trail the day by your other requests still running. An Auto answer that sent no request, such as the 120-second pause after repeated failures on a site, carries neither header. What one Auto call took from the count is in `meta.browserRequests`: see [Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## Cache Behavior

The API doesn't set `Cache-Control`. A response can carry a weak `ETag` computed from its body, but nothing is cached: 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](https://foura.ai/docs/api/endpoints): Request and response envelope shapes
- [API Errors](https://foura.ai/docs/api/errors): How error responses are structured
- [Request Outcomes](https://foura.ai/docs/api/outcomes): Which outcomes are billable
- [Activity Log](https://foura.ai/docs/dashboard/activity-log): Per-request history keyed by request ID
- [Rate Limits](https://foura.ai/docs/api/rate-limits): What each `X-FourA-Limit` value means
