API endpoint 参考
包含所有 FourA API endpoint、request 参数及 response 格式的参考文档。
基础 URL
https://eu.api.foura.ai/api
身份验证
每个 request 都需要在 X-API-Key header 中包含您的 API key:
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 密钥。密钥使用 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)不包含此项。有关哪些结果计费,请参见 请求结果。 |
相同的请求 ID 用作控制台 活动日志(保留 24 小时,每个密钥最近 200 条)中请求和响应载荷预览的键,因此您稍后可以查找确切的请求,并从活动日志直接重放到 Playground。联系支持人员时附上此 ID,可在数秒内精准定位该请求。
$ 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。
端点
通过 MCP 使用这些端点?
@fouradata/mcp服务已将所有四个端点封装为原生 MCP 工具(foura_auto、foura_single、foura_proxy、foura_browser),具备相同的输入结构,并额外提供offload_large选项以支持对 token 友好的大响应处理。主要差异:foura_browser不包含lean字段,且foura_proxy暂不支持 出口位置字段。
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。 |
有关各端点选型的深入指南,请参阅 选择合适的端点 以及 Smart Fetch 指南。
目标 URL 限制
解析为私有、回环或保留 IP 地址范围(RFC 5735、RFC 6598、IPv6 保留块)的目标会在 request 离开 FourA 之前被拒绝并返回 400。仅转发公共主机名和 IP。
{ "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。
{ "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。premium 允许在标准池无法访问页面时将调用升级至高级出口。需要包含高级出口的套餐支持。请参阅 Smart Fetch 中的 exitClass。 |
响应
{
"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。 |
示例
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 和 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 上相同:它是一种配额许可,而非强制指令。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 无法固定: 参见 固定出口。 |
browser |
string | 否 | Chrome | 伪装的浏览器: Chrome, Edge, Safari, Firefox 或 Tor。参见 浏览器配置文件。 |
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 直接指定。
{
"method": "GET",
"url": "https://example.com",
"browser": "Firefox",
"os": "Windows"
}
规则:
- 筛选需要
unblocker(默认开启)。若unblocker关闭,则不会发送任何浏览器 header,因此请求会被拒绝,而不是处于部分应用状态。 - 当多个 profile 匹配时,优先使用最新版本。
- 如果目录中不存在该组合,将返回错误并列出可用项;未知的
profileid 会返回unknown profile '<id>'。请求绝不会伪装成其他浏览器发送。 - 这四个字段同样适用于
POST /proxy/的request对象。
GET /api/profiles 会返回完整目录,且无需 API key:
{
"profiles": [
{ "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
],
"default": "..."
}
构建选择器时,osFamily 是用于过滤的值;os 保留发布名称以供展示。
验证规则
validate 对象用于定义成功和失败的条件。如果命中 fail 条件,request 将被视为失败。如果设置了 accept 条件,则仅匹配的 response 会被视为成功。
{
"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 中触发失败的字符串 |
示例
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:
{
"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 对象,指明供应商名称以及检测是否已通过:
{
"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 表示重试是否获取到了内容。查看 站点检查 了解所有字段和系统的完整列表。 |
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。 |
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:
{
"error": "No eligible proxy found for exit countries: CZ, GB",
"code": "no_eligible_proxy",
"details": { "exitCountries": ["CZ", "GB"] },
"total": 0.084
}
保留请求的 scope 并在稍后重试。仅在工作流的国家/地区要求明确发生变更时,才进行更改或放宽。
示例
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:
{
"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:
{
"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 耗尽尝试次数的原因。
exitClass
某些目标无论尝试多少次,都会拒绝标准池中的出口节点。exitClass: premium 会指示 Proxy,此类 request 除了在标准池内轮换外,还可以升级至 premium 出口。
{
"exitClass": "premium",
"request": { "method": "GET", "url": "https://example.com/report" }
}
发送前有三点需要了解。
**它是一种配额,而非强制指令。**标准池仍会优先竞速获取响应,且通常会胜出。仅当标准池在请求上消耗了一定的预算重试,或者目标明确拒绝时,高级出口才会介入。在尝试任何高级出口前,若标准池已成功响应,则计为普通成功,不消耗高级流量。一旦尝试了高级出口,其流量即被计费,具体说明如下。
**高级出口会严格遵循 exitCountries。**指定国家/地区列表时,高级出口会从其中某个国家/地区发出,响应中的 exitCountry 会注明该国家/地区,机制与标准池相同。
**响应会告知实际提供服务的资源。**指定 class 时,响应会返回 exitClass:
{
"status": 200,
"exitClass": "premium",
"proxy": "Y2QXVK",
"data": "..."
}
premium 表示响应正文由高级出口返回。standard 表示由标准池返回。当无法获取高级出口,或者当前账单周期内套餐包含的高级流量(加上额外购买的流量)已耗尽时,也会返回该结果。这两种情况均非错误,你可以基于每个 request 对账高级流量,而无需依赖月度汇总数据。该值也会通过 X-FourA-Exit-Class 响应 header 返回(参见 Response Headers)。
高级流量按网络传输量统计。 高级尝试会统计其通过网络发送和接收的实际数据量(包含传输过程中的压缩与加密开销),无论最终是否成功返回页面。当另一个出口已返回响应时,仍在进行的尝试会立即终止,其截至终止前产生的流量同样计入统计。高级流量计入你的高级配额,同时也包含在总带宽中:同一批字节会被分别上报两次,但不会累加。当高级出口交付页面时,该出口的流量即为该 request 的全部流量,因此该页面不会再计入标准流量。你的 Usage & Limits 页面会显示总流量、高级流量占比以及用于衡量的基准高级配额。
省略该字段或发送 standard 都会使 request 保持在标准池中运行:仅 premium 允许使用高级出口。显式指定 class 的成功 request 会在 response 中返回 exitClass,省略该字段的 request 则不会返回。
额度耗尽不是错误。 配额用尽后,指定 premium 的 request 仍可继续工作:由标准池提供服务,且 response 标识为 standard。唯一的例外是指定了 exit location 的 request:标准池无法满足此要求,因此会被拒绝。
exitClass: premium 需要包含高级出口的套餐。在未包含高级出口的套餐上,request 绝不会消耗高级出口:在执行任何操作之前,它会被直接拒绝并返回 403 及 X-FourA-Limit: plan_limit_premium(参见 Rate Limits)。
出口位置
高级出口可以从特定国家/地区内的某个位置发出,并根据你的需求持续保留其地址:
{
"exitClass": "premium",
"exitCountries": ["BG"],
"exitCity": "sofia",
"exitLifetimeMin": 15,
"request": { "method": "GET", "url": "https://example.com/" }
}
response 会指明出口节点以及请求流出的国家或地区:
{
"status": 200,
"exitClass": "premium",
"exitCountry": "BG",
"proxy": "1EM4GZY",
"data": "..."
}
该 proxy ID 保留所有这些配置。将其传递给 Single 或 Browser,request 将从同一位置发出,无需附带其他字段。请参阅 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 下的错误载荷,包含错误
No premium exit answered for this request和code: no_eligible_proxy。如果您发送了国家/地区列表,则会包含details.exitCountries。
这些术语与 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 上使用
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。
发送非 Chromium 字符串(例如 Firefox User-Agent),系统会原样呈现,且不附加 Chromium 品牌列表。
示例
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:
{
"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 中。请参阅 站点检测。 |
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,方便您按请求进行查看。无论目标站点是否返回您所需的页面,该出口传输的流量都会计入您 用量与限制 页面中的高级流量以及总带宽。固定出口需要您的套餐支持高级出口且尚有剩余额度;否则该 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):何时让 FourA 为您自动选择路径
- 选择合适的 Endpoint:何时手动选择 Single、Proxy 或 Browser
- 身份验证:管理您的 API key
- 错误处理:从容处理错误
- 站点检查:读取
defense字段并重放通行凭证 - 为什么 Proxy 请求耗尽了重试次数:读取
attemptReport并采取相应操作 - 速率限制:了解请求限制
- 快速入门:30 秒内完成您的首个请求