# API endpoint 参考

> URL: https://foura.ai/zh/docs/api/endpoints
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

包含所有 FourA API endpoint、request 参数及 response 格式的参考文档。

## 基础 URL

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

## 身份验证

每个 request 都需要在 `X-API-Key` header 中包含您的 API 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"}'
```

在 [控制台](https://foura.ai/dashboard) 中创建和管理 API 密钥。密钥使用 `pk_live_` 前缀。

## 响应头

来自 `/api/*` 的响应包含两个关联标头:

| Header | Value | Description |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | 分配给该请求的唯一 ID。在所有响应中返回（包括 4xx 和 5xx），但 FourA 完全无法读取请求体的情况除外: `400 Invalid JSON in request body` 和 `413` 会在分配 ID 之前被拒绝。建议在您的系统记录此 ID。 |
| `X-FourA-Credits` | integer | 该请求消耗的积分。在到达引擎的所有响应中返回，无论是成功还是失败（工作已执行）。在引擎运行前被 FourA 拒绝的调用（缺少或无效的密钥、套餐或平台限制、被拒绝的目标或代理 ID）不包含此项。有关哪些结果计费，请参见 [请求结果](https://foura.ai/docs/api/outcomes)。 |

相同的请求 ID 用作控制台 [活动日志](https://foura.ai/docs/dashboard/activity-log)（保留 24 小时，每个密钥最近 200 条）中请求和响应载荷预览的键，因此您稍后可以查找确切的请求，并从活动日志直接重放到 [Playground](https://foura.ai/docs/dashboard/playground)。联系支持人员时附上此 ID，可在数秒内精准定位该请求。

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

完整列表及使用提示请参阅 [Response Headers](https://foura.ai/docs/api/response-headers)。

## 端点

> **通过 MCP 使用这些端点？** [`@fouradata/mcp` 服务](https://foura.ai/docs/mcp/server)已将所有四个端点封装为原生 MCP 工具（`foura_auto`、`foura_single`、`foura_proxy`、`foura_browser`），具备相同的输入结构，并额外提供 `offload_large` 选项以支持对 token 友好的大响应处理。主要差异：`foura_browser` 不包含 `lean` 字段，且 `foura_proxy` 暂不支持 [出口位置](#exit-location)字段。

FourA 提供四个 request 端点，分别针对不同场景进行了优化：

| Endpoint | 适用场景 |
|----------|----------|
| `POST /auto/` | 智能抓取。传入 URL 后，FourA 会选择成本最低的有效路径（轮换 proxy 或浏览器，以及包含 `forceProxy: false` 的直连 request），并记住每个主机的有效方案。 |
| `POST /single/` | 快速 HTTP request、静态页面、API |
| `POST /proxy/` | 受保护的站点，具备自动 proxy 轮换，支持可选的目标可见国家范围限定 |
| `POST /browser/` | JavaScript 渲染的页面、SPA |
| `GET /profiles` | 适用于 `single` 和 `proxy` 的浏览器配置文件目录。公开，无需 API key。 |

有关各端点选型的深入指南，请参阅 [选择合适的端点](https://foura.ai/docs/guides/choosing-task-type) 以及 [Smart Fetch 指南](https://foura.ai/docs/guides/smart-fetch)。

## 目标 URL 限制

解析为私有、回环或保留 IP 地址范围（RFC 5735、RFC 6598、IPv6 保留块）的目标会在 request 离开 FourA 之前被拒绝并返回 400。仅转发公共主机名和 IP。

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

指向 FourA 自身 API 主机（`eu.api.foura.ai` 或 `api.foura.ai`）的目标也会在所有四个 endpoint 上被拒绝并返回 400，此操作发生在任何抓取或计费之前。包含空格或控制字符的 URL 同样会在 Single、Proxy 和 Auto 上被拒绝并返回 400；请将空格编码为 `%20`（Browser 模式会按 Chrome 的方式抓取）。FourA 唯一会抓取的此类页面是 [`/inspect`](https://foura.ai/docs/api/inspect)。

```json
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
```

---

## 智能获取 (Auto)

`POST /api/auto/`

传入目标 URL 以及可选的 `validate` 规则。FourA 会按成本优先阶梯逐级尝试（轮换 proxy，随后完整浏览器），并在首个返回符合规则响应的层级停止。启用 `forceProxy: false` 时，会先执行低成本的直连探测。针对同一主机的后续调用，会重放预热 session，从而降低二次请求成本。

无需手动调优重试次数、池大小或 proxy 数量，FourA 会针对每个主机自动学习。

### 请求体

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `url` | string | 是 | - | 目标 URL |
| `method` | string | 否 | `"GET"` | HTTP 方法 |
| `headers` | [string, string][] | 否 | - | 发送到目标的 headers，格式为 [name, value] 键值对。除浏览器层级外，所有层级都会发送这些 headers。你发送的 `Cookie` 将原样到达目标站点，已存储 session 的 cookie 仅会在名称不冲突时补充添加。已存储 session 的 `userAgent` 会替换你传入的 `User-Agent`。Proxy 层级会忽略条件 headers（如 `If-None-Match`），除非你的 `validate.status.accept` 明确列出了 `304`。 |
| `data` | any | 否 | - | 非 GET 请求的请求体 |
| `validate` | object | 否 | - | 成功判定条件，格式与 Single Request 的 `validate` 相同（见下文）。向 auto 描述正常页面的特征，以便区分真实内容与验证页面。 |
| `returnSession` | boolean | 否 | `true` | 在响应中包含胜出的 session（`proxy`、`cookies`、`userAgent`），以便通过 `/api/single/` 或 `/api/browser/` 进行重放。 |
| `forceProxy` | boolean | 否 | `true` | 始终通过轮换 proxy 路由。设置为 `false` 可在目标允许时使用成本更低的直连路径（部分防御机制对 proxy 流量更为严格）。 |
| `timeout_ms` | integer | 否 | `120000` | 整个调用的总时间预算，单位为毫秒。所有子尝试均在此预算内运行。最小值为 `5000`，最大值为 `180000`。 |
| `ignoreProxies` | string[] | 否 | - | 所有子尝试中需要规避的 proxy ID。使用此前 `/api/auto/` 或 `/api/proxy/` 响应返回的 ID。 |
| `followRedirects` | integer | 否 | `5` | 低成本阶梯层级中跟随的最大重定向次数。设为 `0` 表示禁用。最大值为 `20`。 |
| `exitClass` | string | 否 | - | `standard` 或 `premium`，用法同 [Proxy Request](#exitclass)。`premium` 允许在标准池无法访问页面时将调用升级至高级出口。需要包含高级出口的套餐支持。请参阅 [Smart Fetch 中的 exitClass](#exitclass-on-smart-fetch)。 |

### 响应

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
```

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `status` | number | 目标返回的 HTTP 状态码。 |
| `data` | string | 响应体文本，无论由哪一级阶梯返回。JSON 页面将作为 JSON 文本返回，需自行解析。 |
| `headers` | array or object | 目标响应 headers。Single 和 proxy 阶梯返回逐跳 header 对象的数组；browser 阶梯返回扁平对象。 |
| `meta.rung` | string | 交付响应的阶梯层级。取值之一：`probe`（低成本直连 request，仅限 `forceProxy: false`）、`proxy`（轮换 proxy）、`browser`（完整浏览器渲染）、`cache`（复用预热会话）、`warmup`（先抓取站点入口页并利用其 cookie 打开深层 URL）或 `fail`（没有阶梯产生有效响应）。 |
| `meta.solved` | boolean | 页面是否需要额外步骤（验证页面）且已在本次调用中完成。 |
| `meta.attempts` | number | 成功前进行的子重试次数。 |
| `meta.credits` | number | 本次调用消耗的总积分。与 `X-FourA-Credits` 一致。 |
| `meta.attemptsByEngine` | object | 发送到 `single`、`proxy` 和 `browser` 的 request 数。因已被发送，套餐拒绝的浏览器 request 也会计入。 |
| `meta.browserRequests` | number | 占用每日配额槽位的浏览器 request 数。套餐拒绝的浏览器 request 不占用配额。 |
| `meta.exitClass` | string | 交付响应的出口类别，当 request 指定了 `exitClass` 时存在：`premium` 或 `standard`。相同值也会通过 `X-FourA-Exit-Class` 响应 header 传递。 |
| `session.proxy` | string | 交付响应的 proxy 编码 ID。可在 Single 或 Browser request 中复用。当 `returnSession` 为 `true` 时存在。 |
| `session.cookies` | array | 供复用的 cookie 列表，每项至少包含 `name` 和 `value`。browser 阶梯返回浏览器的 cookie jar。proxy 阶梯或直连探测仅返回解锁页面所需的 cookie（例如站点验证页设置的 cookie），不会返回页面设置的所有 cookie，因此列表可能为空。当 `returnSession` 为 `true` 时存在。 |
| `session.userAgent` | string | 成功尝试中所使用的 User-Agent。当 `returnSession` 为 `true` 时存在。 |
| `error` | string | 调用失败时的错误信息。 |
| `attemptReport` | object | 调用失败时按原因分类的未返回页面的引擎 request。参见 [Smart Fetch](https://foura.ai/docs/guides/smart-fetch)。 |

### 示例

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

### 注意事项

- Auto 是一个协调器。它在内部调用 Single、Proxy 或 Browser，并将您的 API key 转发给每个子调用。Auto 调用在您的 [Activity Log](https://foura.ai/docs/dashboard/activity-log) 和 Overview 中计为一次 request，消耗其子调用积分的总和；子调用作为尝试记录列在其下方，绝不会单独计为独立的 request。
- 传入 `validate.data.accept`，并附带仅真实页面才包含的子字符串。若没有它，Auto 无法区分真实的 200 状态与返回状态码 200 的质询插页。
- 页面被移除属于站点的正常响应，而非拒绝服务。当两个出口节点返回相同的 `404` 或 `410` 且您的 `validate` 不接受它时，调用将以此 `status` 结束，并返回以 `the site answered` 开头的 `error`。将该状态列入 `validate.status.accept`，Auto 就会交付首个具有该状态且通过您其余 `validate` 的 response。您在此处列出的任何其他状态同样适用，但 `403`、`429`、`503` 和 `202` 除外，站点在返回质询页面时也会发送这些状态。
- `timeout_ms` 限制整个调用的总耗时。对受保护站点的首次冷请求可能需要数十秒；复用预热 session 通常在一秒内完成。

### Smart Fetch 上的 exitClass

`exitClass` 在 Smart Fetch 上的机制与在 [Proxy Request](#exitclass) 上相同：它是一种配额许可，而非强制指令。Auto 会首先尝试标准池。当标准池无法访问该页面且 request 指定了 `premium` 时，Auto 会通过高级出口在浏览器中打开页面。在此建立的 session 将服务于后续同样指定 `premium` 且访问同一站点的调用；未指定它的调用绝不会复用该 session。

用尽配额不属于错误。一旦您套餐中的高级流量在当前计费周期内耗尽，调用将在标准池中继续进行，且 `meta.exitClass` 会显示 `standard`。在不包含高级出口的套餐中，发送 `exitClass: premium` 的调用将在开始执行前被拒绝，返回带有 `X-FourA-Limit: plan_limit_premium` 的 `403`。

高级流量的统计方式与 Proxy Request 相同。在浏览器中打开页面所加载的内容多于页面本身，因此高级 Smart Fetch 页面消耗的高级流量要高于通过 Proxy Request 获取的同一页面。为了降低流量消耗，高级 Smart Fetch 页面加载时不包含图片、字体和媒体，并会拦截来自已知广告、分析和用户同意管理提供商的脚本。

---

## Single Request

`POST /api/single/`

发送具有高度拟真浏览器级底层网络特征的 HTTP request，无需启动真实浏览器。这是速度最快的 endpoint。

### 请求体

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `method` | string | 是 | - | HTTP 方法: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| `url` | string | 是 | - | 目标 URL。在 URL 任意位置使用 `{ts}` 可插入当前时间戳以防止缓存。 |
| `headers` | [string, string][] | 否 | - | 自定义 headers，格式为 [name, value] 键值对 |
| `unblocker` | boolean | 否 | `true` | 发送真实的浏览器 headers (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding)。默认开启。设置为 `false` 时，FourA 不会添加任何浏览器 headers，仅发送你传入的内容。 |
| `timeout_ms` | number | 否 | 15000 | 总超时时间，单位为毫秒 (最大值: 120000) |
| `connect_timeout_ms` | number | 否 | 5000 | 连接超时时间，单位为毫秒 |
| `accept_timeout_ms` | number | 否 | 5000 | 接收超时时间，单位为毫秒 (等待连接建立的时间) |
| `server_response_timeout_ms` | number | 否 | 15000 | 服务器响应超时时间，单位为毫秒 (等待首字节的时间) |
| `dns_cache_timeout_sec` | number | 否 | 120 | DNS 缓存 TTL，单位为秒 (最大值: 240) |
| `followRedirects` | number | 否 | disabled | 最大重定向跟随次数 (0-20)。省略则禁用。 |
| `tryJsonData` | boolean | 否 | false | 若可能，将 response body 解析为 JSON |
| `returnBuffer` | boolean | 否 | false | 返回原始 buffer 而非解码后的字符串 |
| `data` | any | 否 | - | 请求 body (字符串或对象，自动序列化为 JSON) |
| `proxy` | string | 否 | - | 来自先前 response 的 proxy ID，用于固定相同的出口。原样传回该不透明字符串即可。原始 proxy 地址会被拒绝并返回 `400 Invalid proxy format`。部分 ID 无法固定: 参见 [固定出口](#pinning-an-exit)。 |
| `browser` | string | 否 | Chrome | 伪装的浏览器: Chrome, Edge, Safari, Firefox 或 Tor。参见 [浏览器配置文件](#browser-profiles)。 |
| `os` | string | 否 | - | 伪装的操作系统: Windows, macOS, Android 或 iOS。系统族名称可匹配其任意版本。 |
| `version` | string | 否 | newest | 伪装的浏览器版本，如目录中所列。若有多个匹配项，则选用最新版本。 |
| `profile` | string | 否 | - | 来自 `GET /api/profiles` 的确切 profile id，用于替代上述三个字段。 |
| `validate` | object | 否 | - | 响应校验规则 (见下文) |

### 浏览器配置文件

默认情况下，request 会伪装为最新的 Google Chrome。某些目标仅接受特定浏览器而拒绝其他浏览器，因此可通过 `browser`、`os` 和 `version` 筛选已测量的配置文件目录，或通过 `profile` 按 id 直接指定。

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

规则：

- 筛选需要 `unblocker`（默认开启）。若 `unblocker` 关闭，则不会发送任何浏览器 header，因此请求会被拒绝，而不是处于部分应用状态。
- 当多个 profile 匹配时，优先使用最新版本。
- 如果目录中不存在该组合，将返回错误并列出可用项；未知的 `profile` id 会返回 `unknown profile '<id>'`。请求绝不会伪装成其他浏览器发送。
- 这四个字段同样适用于 `POST /proxy/` 的 `request` 对象。

`GET /api/profiles` 会返回完整目录，且无需 API key：

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

构建选择器时，`osFamily` 是用于过滤的值；`os` 保留发布名称以供展示。

### 验证规则

`validate` 对象用于定义成功和失败的条件。如果命中 `fail` 条件，request 将被视为失败。如果设置了 `accept` 条件，则仅匹配的 response 会被视为成功。

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

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `validate.status.accept` | number[] | 允许接收的 HTTP 状态码 |
| `validate.status.fail` | number[] | 判定拒绝的 HTTP 状态码 |
| `validate.headers.accept` | object | 在任意重定向跳转中只要有一对匹配，response 即判定通过。名称和值不区分大小写，支持部分文本匹配。 |
| `validate.headers.fail` | object | 触发失败的 header 键值对 |
| `validate.data.accept` | string[] | 当 body 包含这些字符串中的至少一个时，response 判定通过 |
| `validate.data.fail` | string[] | response body 中触发失败的字符串 |

### 示例

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

当目标在返回响应主体前执行 Bot 检测时，响应中还会携带一个 `defense` 对象，指明供应商名称以及检测是否已通过：

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

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `status` | number | 目标返回的 HTTP 状态码 |
| `headers` | array | 每个重定向跃点一个对象。每个对象均包含一个包含状态行和所有 response header 的 `result` 字段。多值 header (`Set-Cookie`, `Link`, `WWW-Authenticate`) 以字符串数组形式返回。 |
| `data` | string/object | 响应体 (若 `tryJsonData` 为 true 则为 JSON) |
| `total_time` | number | 总请求耗时，单位为秒 |
| `proxy` | string | 请求所经 proxy 的编码 ID (仅在请求中提供了 `proxy` 时返回)。在后续调用中复用它可以固定相同的出口。 |
| `defense` | object | 当目标对此请求运行了 Bot 检查，或使用站点自身 cookie 重试并获取到响应体时出现。`defense.solved` 表示是否通过了检查，`defense.retry` 表示重试是否获取到了内容。查看 [站点检查](https://foura.ai/docs/api/site-checks) 了解所有字段和系统的完整列表。 |
| `error` | string | 请求失败时的错误信息 |

---

## Proxy 请求

`POST /api/proxy/`

通过轮换 proxy 路由您的请求，失败时自动重试。可选将节点选择限定在目标可见的出口国家范围内。

### 请求体

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `request` | object | 是 | - | 单个 request body (字段与上文的 Single Request 相同) |
| `timeout_ms` | number | 否 | 45000 | 所有尝试的总超时时间，单位为毫秒 (最大值: 120000) |
| `maxTries` | number | 否 | 5 | 失败次数达到此阈值后，FourA 将停止发起新的尝试 (最大值: 90)。由于尝试是并行运行的，实际完成的次数可能会略多于该数值。 |
| `ignoreProxies` | string[] | 否 | - | 需要从轮换中排除的 proxy ID 列表 (使用之前 response 返回的 ID) |
| `exitCountries` | string[] | 否 | - | 目标可见的双字母国家代码严格允许列表 (例如 `["CZ", "GB"]`)。传入的值会自动去除首尾空格、转为大写并去重。标准池中未知国家的出口会被排除，且标准池绝不会回退到未请求的国家。premium 出口同样会从所列国家之一发起。 |
| `exitClass` | string | 否 | - | `standard` 或 `premium`。当标准池在受保护的目标上遇到困难时，`premium` 允许 request 升级到 premium 出口。需要包含 premium 出口的套餐计划。 |
| `exitState` | string | 否 | - | 出口所在的地区。需要设置 `exitClass: premium` 且在 `exitCountries` 中仅指定一个国家。请参阅 [Exit location](#exit-location)。 |
| `exitCity` | string | 否 | - | 出口所在的城市。需要设置 `exitClass: premium` 且在 `exitCountries` 中仅指定一个国家。 |
| `exitAsn` | string | 否 | - | 出口所在的网络 (按 AS 号指定)，例如 `8866`。需要设置 `exitClass: premium` 且在 `exitCountries` 中仅指定一个国家。 |
| `exitOs` | string | 否 | - | `windows`、`android`、`ios` 或 `mac`: 该地址所属的设备类型。需要设置 `exitClass: premium`。 |
| `exitLifetimeMin` | integer | 否 | - | 出口保持其地址的分钟数，范围为 `3` 到 `1440`。需要设置 `exitClass: premium`。 |

### exitCountries 作用域

选择机制使用最新可用的目标可见国家元数据，通常在大约十分钟内刷新。这并不是 request 期间的实时地理位置查询。请勿从 proxy 主机地址推断提供服务的国家。

如果当前池中没有与所请求国家匹配的节点，且 request 未指定 `exitClass: premium`，则 response 将返回带有错误包装的 HTTP 200:

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

保留请求的 scope 并在稍后重试。仅在工作流的国家/地区要求明确发生变更时，才进行更改或放宽。

### 示例

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

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `proxy` | string | 所使用 proxy 的编码标识符。在 Single 或 Browser request 中将其作为 `proxy` 字段传入以复用，或在下一次 Proxy request 中通过 `ignoreProxies` 跳过它。 |
| `exitCountry` | string | 处理该 request 的 proxy 所在目标可见两位国家代码。仅当 request 设置了 `exitCountries` 时存在，无论由哪类出口节点处理。在信任 response 之前，请务必核对它是否属于您请求的代码之一。 |
| `exitClass` | string | 处理此 request 的出口节点类别，当 request 指定了类别并在成功响应时返回。`premium` 表示由高级出口返回 body；`standard` 表示由标准池返回。失败的调用未处理任何内容，因此不包含 `exitClass`；请查看其 `attemptReport` 获取各次尝试遇到的情况。 |
| `total` | number | 外部实际耗时，单位为秒（浮点数）。包含 proxy 选择、重试以及成功的尝试。`total_time` 仅指内部 request 耗时；`total` 始终 >= `total_time`。 |
| `profile` | string | 轮换选择的浏览器配置，**仅**在它与您请求的配置不一致时出现。缺失表示 request 完全按原样发出。在后续调用中将该 ID 作为 `profile` 传回，以保留正常工作的浏览器。 |
| `error` | string | request 失败时的错误信息。发生作用域未命中时，`code` 为 `no_eligible_proxy`，且 `details.exitCountries` 会回显规范化后的作用域。 |
| `attemptReport` | object | 存在于**每一个**失败的 Proxy 调用中。统计尝试过程中遇到的情况，以避免被封禁的池、失效的池以及从未匹配的 `validate` 规则显示为完全相同的错误。详见下文。 |
| `request` | object | 存在于失败的 Proxy 调用中：包含 FourA 运行的 request，已填充默认值并保留您发送的原样 `ignoreProxies`。 |

所有 Single Request response 字段均包含在内，其中包括 `defense`：遇到 Bot 检查的 proxy 尝试会以与 Single 相同的方式报告。

### Proxy 调用失败的原因

无论尝试过程如何，`Download maxTry limit reached` 的显示内容都是一致的，因此每个失败的 Proxy response 都会在错误信息旁附带一个 `attemptReport`：

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

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `total` | integer | 尝试次数 |
| `noResponse` | integer | 出口节点未响应，因此从未访问到目标站点 |
| `defense` | integer | 站点已响应，且在响应中识别出 Bot 验证 |
| `contentRejected` | integer | HTTP 200，无 Bot 验证，仅被您的 `validate.data` 拒绝 |
| `statusRejected` | integer | 站点已响应，无 Bot 验证，被您的 `validate.status` 拒绝 |
| `other` | integer | 已响应，且不属于上述任何情况 |
| `vendors` | string[] | 在任务中任一环节识别出的 Bot 验证供应商 |
| `profilesTried` | string[] | 任务发送的浏览器 Profile，按首次使用顺序排列。`default` 表示您的 request 未作修改直接发出。 |
| `summary` | string | 基于计数值生成的一句话描述，可安全记录到日志 |

`error` 字符串保持不变，因此匹配该值的客户端仍可正常工作。针对各项计数的处理方式：[Proxy Request 耗尽尝试次数的原因](https://foura.ai/docs/troubleshooting/proxy-attempt-report)。

### exitClass

某些目标无论尝试多少次，都会拒绝标准池中的出口节点。`exitClass: premium` 会指示 Proxy，此类 request 除了在标准池内轮换外，还可以升级至 **premium 出口**。

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

发送前有三点需要了解。

**它是一种配额，而非强制指令。**标准池仍会优先竞速获取响应，且通常会胜出。仅当标准池在请求上消耗了一定的预算重试，或者目标明确拒绝时，高级出口才会介入。在尝试任何高级出口前，若标准池已成功响应，则计为普通成功，不消耗高级流量。一旦尝试了高级出口，其流量即被计费，具体说明如下。

**高级出口会严格遵循 `exitCountries`。**指定国家/地区列表时，高级出口会从其中某个国家/地区发出，响应中的 `exitCountry` 会注明该国家/地区，机制与标准池相同。

**响应会告知实际提供服务的资源。**指定 class 时，响应会返回 `exitClass`：

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

`premium` 表示响应正文由高级出口返回。`standard` 表示由标准池返回。当无法获取高级出口，或者当前账单周期内套餐包含的高级流量（加上额外购买的流量）已耗尽时，也会返回该结果。这两种情况均非错误，你可以基于每个 request 对账高级流量，而无需依赖月度汇总数据。该值也会通过 `X-FourA-Exit-Class` 响应 header 返回（参见 [Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class)）。

**高级流量按网络传输量统计。** 高级尝试会统计其通过网络发送和接收的实际数据量（包含传输过程中的压缩与加密开销），无论最终是否成功返回页面。当另一个出口已返回响应时，仍在进行的尝试会立即终止，其截至终止前产生的流量同样计入统计。高级流量计入你的高级配额，同时也包含在总带宽中：同一批字节会被分别上报两次，但不会累加。当高级出口交付页面时，该出口的流量即为该 request 的全部流量，因此该页面不会再计入标准流量。你的 [Usage & Limits](https://foura.ai/docs/dashboard/quota) 页面会显示总流量、高级流量占比以及用于衡量的基准高级配额。

省略该字段或发送 `standard` 都会使 request 保持在标准池中运行：仅 `premium` 允许使用高级出口。显式指定 class 的成功 request 会在 response 中返回 `exitClass`，省略该字段的 request 则不会返回。

**额度耗尽不是错误。** 配额用尽后，指定 `premium` 的 request 仍可继续工作：由标准池提供服务，且 response 标识为 `standard`。唯一的例外是指定了 [exit location](#exit-location) 的 request：标准池无法满足此要求，因此会被拒绝。

`exitClass: premium` 需要包含高级出口的套餐。在未包含高级出口的套餐上，request 绝不会消耗高级出口：在执行任何操作之前，它会被直接拒绝并返回 403 及 `X-FourA-Limit: plan_limit_premium`（参见 [Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits)）。


### 出口位置

高级出口可以从特定国家/地区内的某个位置发出，并根据你的需求持续保留其地址：

```json
{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}
```

response 会指明出口节点以及请求流出的国家或地区：

```json
{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}
```

该 `proxy` ID 保留所有这些配置。将其传递给 Single 或 Browser，request 将从同一位置发出，无需附带其他字段。请参阅 [Pinning an Exit](#pinning-an-exit)。

规则：

- 包含 `exitState`、`exitCity`、`exitAsn`、`exitOs` 和 `exitLifetimeMin` 中的任意一项，都会仅通过高级出口发送 request。标准池不会进行尝试，因为它无法支持这些选项。
- 它们需要 `exitClass: premium`。若缺少该字段，request 将被拒绝并返回指出该字段的 400 错误。
- `exitState`、`exitCity` 和 `exitAsn` 仅存在于单一国家/地区内，因此需要在 `exitCountries` 中精确指定一个国家/地区。`exitOs` 和 `exitLifetimeMin` 可对应多个国家/地区：出口会采用其中之一，并在 response 的 `exitCountry` 中指明。
- `exitState`、`exitCity`、`exitAsn` 和 `exitOs` 需要同时包含地理定位和高级出口的套餐。
- 若无剩余高级流量，request 将被拒绝并返回带有 `X-FourA-Limit: plan_limit_premium` 的 403 错误，因为标准池无法提供服务。
- 如果该位置没有高级出口响应，response 将是一个类似于 [exitCountries scoping](#exitcountries-scoping) 下的错误载荷，包含错误 `No premium exit answered for this request` 和 `code: no_eligible_proxy`。如果您发送了国家/地区列表，则会包含 `details.exitCountries`。

这些术语与 [proxy port](https://foura.ai/docs/api/proxy-port) 中用于 `state`、`city`、`asn` 和 `os` 的术语一致。

### 浏览器配置文件轮换

Proxy 会轮换出口。当目标站点拒绝 FourA 呈现的浏览器而非其来源出口时，Proxy 还会切换到目录中的另一个浏览器系列。它不会增加尝试次数：轮换只会改变重试时发送的内容，绝不会决定是否发生重试。

Proxy 还会临时记住站点上次接受的系列，因此后续对同一站点的调用可以直接使用该系列开始，而非使用默认系列。与轮换选择的任何系列一样，response 会在 `profile` 中指明它。

内部 `request` 上显式设置的 `profile`、`browser`、`os` 或 `version` 绝不会被覆盖；自带 `User-Agent` 或 `Cookie` header 的 request 也同样不会被覆盖，因为 clearance 与获取它时所用的签名绑定。

---

## 浏览器请求

`POST /api/browser/`

在 Chrome 浏览器实例中打开您的 URL。页面加载完成，JavaScript 执行完毕，您将获得完整渲染的 HTML 以及 cookie 容器。

### 请求体

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `url` | string | 是 | - | 目标 URL |
| `headers` | object | 否 | - | 键值对形式的自定义 header |
| `cookies` | array | 否 | - | 要设置的 Cookie：`[{name, value, domain?}]` |
| `userAgent` | string | 否 | - | 自定义 User-Agent 字符串 |
| `unblocker` | boolean | 否 | `true` | 完成页面加载前要求的检查（质询页面或类似的关卡）。默认开启。设置为 `false` 则按原样渲染页面返回的任何内容，包括质询页面。 |
| `proxy` | string | 否 | - | 来自先前响应的 proxy ID，用于固定相同的出口。请原样传回该不透明字符串。原始 proxy 地址会被拒绝并返回 `400 Invalid proxy format`。 |
| `timeout_ms` | number | 否 | 30000 | 页面加载超时时间，单位为毫秒（最大值：120000） |
| `checkStatus` | number | 否 | - | 预期的 HTTP 状态码（如果不一致则请求失败） |
| `checkText` | string | 否 | - | 渲染后的页面中必须出现的文本 |
| `lean` | boolean | 否 | `false` | 排除图片、字体和媒体文件，以及发往已知广告、分析、授权同意和社交服务的请求。页面本身、其自身的脚本和样式，以及验证步骤所需的任何内容仍会加载。可用于降低页面消耗的流量，例如通过固定的高级出口。 |

### 将浏览器时钟与出口匹配

页面可以读取浏览器的时区，并将其与检测到的 IP 所在国家/地区进行比对。时区不匹配是 Bot 检测程序成本最低的识别信号之一，而消除这种不匹配无需任何成本。

你无需执行任何操作。FourA 会从 `proxy` ID 中读取国家/地区，浏览器则会报告属于该国家/地区的时区。

- 这是**出口**国家/地区，即目标看到的国家/地区，而不是 proxy 的托管地。这两者经常不一致，足以产生影响。
- 当 FourA 不知道出口的国家/地区时，它会保持浏览器时钟不变，而不是凭空猜测。当你在 [Proxy Request](#exit-location) 上使用 `exitCountries` 请求了指定国家/地区时，高级出口就具有已知的国家/地区。
- 只有时钟会跟随国家/地区调整。`Accept-Language` 以及站点提供的内容保持不变，因此页面不会突然为你切换语言。

### `userAgent` 参数

发送 `userAgent` 后，页面、其 Worker 以及目标看到的都将是该精确字符串。FourA 还会据此推导出匹配的 Client Hints（`sec-ch-ua`、`sec-ch-ua-platform`、`navigator.platform`，以及检测程序按名称请求的高熵值），确保请求不会在 header 中声明一种浏览器，而在 JavaScript 中呈现另一种。

响应中的 `userAgent` 即为实际呈现的值。这在重放通过凭证时非常重要：`cf_clearance` cookie 与获取它的出口以及 User-Agent 绑定，因此请传回响应所报告的字符串，而不是你认为使用的字符串。请参阅 [Site checks](https://foura.ai/docs/api/site-checks)。

发送非 Chromium 字符串（例如 Firefox User-Agent），系统会原样呈现，且不附加 Chromium 品牌列表。

### 示例

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

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `status` | number | 目标返回的 HTTP 状态码 |
| `headers` | object | 响应 headers |
| `body` | string or object | 完整渲染的页面内容。当 content-type 为 HTML 时为字符串形式的 HTML；当页面返回 JSON 并被自动解析时为对象。 |
| `cookies` | array | 来自页面的完整 cookie 对象数组。每个 cookie 均包含 `name`、`value`、`domain`、`path`、`expires`、`httpOnly`、`secure`、`sameSite` 以及其他 cookie 属性。 |
| `userAgent` | string | 所使用的浏览器 User-Agent |
| `defenseSolved` | boolean | 若本次调用遇到并成功绕过机器人防御则为 `true`，否则为 `false`。用于决定本次调用扣除 5 点还是 10 点积分。 |
| `defenses` | object | `present` 列出页面加载期间识别出的所有供应商，`cleared` 列出最终页面已获得放行凭证的供应商。某个供应商可能出现在 `present` 中，但从未出现在 `cleared` 中。请参阅 [站点检测](https://foura.ai/docs/api/site-checks)。 |
| `proxy` | string | 本次请求所通过代理的已编码 ID（仅当请求中提供了 `proxy` 时返回）。可在后续调用中复用它以保持相同的出口。 |
| `error` | string | 请求失败时的错误信息 |

---

## 固定出口

在 Single 或 Browser 请求中传入 `proxy` 值可以固定先前调用所使用的出口。请原样回传该不透明 ID，切勿传入代理地址。来自指定了国家、地点或生命周期的 Proxy 请求的 ID 会保留这些设置，因此固定请求无需传入其他字段。

以下三种值会被拒绝，均返回 400 状态码：

| 错误 | 含义 |
|-------|---------|
| `Invalid proxy format` | 该值并非 FourA 颁发的 ID。直接传入原生代理地址会触发此错误。 |
| `Proxy not found` | ID 已成功解码，但不再解析到活跃的出口。请通过新的调用获取新 ID。 |
| `Managed exit: this proxy id cannot be pinned to a request` | 出口存在，但 FourA 不会为指定请求保留它。当您的套餐中已无可用高级流量额度时，高级出口的 ID 会触发此错误。可复用返回该 ID 的会话，或通过 `POST /api/proxy/` 发起调用并采用其自动选择的出口。 |

固定的高级出口按高级流量计费。响应中包含 `X-FourA-Exit-Class: premium`，方便您按请求进行查看。无论目标站点是否返回您所需的页面，该出口传输的流量都会计入您 [用量与限制](https://foura.ai/docs/dashboard/quota) 页面中的高级流量以及总带宽。固定出口需要您的套餐支持高级出口且尚有剩余额度；否则该 ID 将被拒绝并返回上述 managed-exit 400 错误。

## HTTP 状态码

| 状态码 | 含义 |
|------|---------|
| 200 | 请求已完成（检查内部 `status` 以获取目标响应） |
| 400 | 无效的请求体、参数、目标 IP 位于私有/保留网段、目标指向 FourA 自身的 API 主机、URL 内部包含未编码的空格（Single、Proxy、Auto），或无法固定 proxy ID。在 Single、Proxy 和 Browser 上，未通过验证的字段会明确标注：`Invalid request: <field>: <reason>`，最多五个字段。不计费。Auto 对相同的错误返回 HTTP 200 并在响应体中包含 `status: 400`。 |
| 401 | 缺少 API key 或 API key 无效 |
| 403 | 该 endpoint 或参数未包含在您的套餐中。`X-FourA-Limit` 会指明具体项：`plan_limit_feature` 或 `plan_limit_premium`。 |
| 404 | `Not Found`：该路径下不存在 endpoint。 |
| 413 | JSON 请求体超过 100 KB。响应不是 JSON，且不包含 `X-FourA-Request-Id`。 |
| 429 | 套餐额度限制（已设置 `X-FourA-Limit`）或平台的共享每分钟配额（无 header） |
| 500 | 内部服务器错误 |
| 502 | `Upstream unavailable`：FourA 无法连接至其引擎。`Malformed JSON from backend`：引擎已响应，但 FourA 无法读取回复。请重试。 |
| 503 | 服务暂时停用或已达容量上限，当 FourA 暂时无法验证您的密钥时返回 `API key check temporarily unavailable`（请在 `Retry-After` 后重试），或在引擎重启期间返回 `Backend service unavailable`。在 Browser 上，当所有实例繁忙时，页面最多等待 10 秒以获取空闲浏览器，如果超时仍无空闲实例则返回 `Backend service unavailable`。 |
| 504 | `Upstream timeout`。引擎未在此请求的时间预算内完成。请增大 `timeout_ms` 或重试。 |

## 后续步骤

- [智能提取 (Auto)](https://foura.ai/docs/guides/smart-fetch)：何时让 FourA 为您自动选择路径
- [选择合适的 Endpoint](https://foura.ai/docs/guides/choosing-task-type)：何时手动选择 Single、Proxy 或 Browser
- [身份验证](https://foura.ai/docs/getting-started/authentication)：管理您的 API key
- [错误处理](https://foura.ai/docs/api/errors)：从容处理错误
- [站点检查](https://foura.ai/docs/api/site-checks)：读取 `defense` 字段并重放通行凭证
- [为什么 Proxy 请求耗尽了重试次数](https://foura.ai/docs/troubleshooting/proxy-attempt-report)：读取 `attemptReport` 并采取相应操作
- [速率限制](https://foura.ai/docs/api/rate-limits)：了解请求限制
- [快速入门](https://foura.ai/docs/getting-started/quick-start)：30 秒内完成您的首个请求
