智能获取 (Auto)
你向 FourA 提供一个 URL 和一条关于真实页面应包含内容的 validate 规则。其余工作由 FourA 完成:它按成本效益阶梯逐步尝试,停在首个返回满足你规则的响应阶梯上,并按主机记录有效策略,使同一站点的下一次调用成本更低。
本指南介绍 auto 的底层运行机制、适用场景以及如何解析其响应。有关参数参考,请参阅 API Endpoints。
核心概念
大多数抓取方案要求你预先指定引擎。Single 最快,Proxy 提供轮换,Browser 负责处理 JavaScript。一旦预判错误,就会浪费积分或遭遇拦截。
Auto 改变了这种模式。你只需定义成功标准(validate),无需指定实现方式。FourA 依次尝试不同阶梯,直到某一阶梯成功:
- 低成本探测(single,直接来自 FourA 自有网络)
- Browser,直接来自 FourA 自有网络,支持 JavaScript,并在站点发起质询时调用求解器
- 轮换 proxy single
- 通过 proxy 运行 Browser,用于处理最严格的目标
一旦某个阶梯返回符合你 validate 规则的响应,Auto 就会立即停止。
还有一个阶梯独立于该顺序之外。当某个出口成功连接站点但站点拒绝你请求的深层 URL 时,auto 会通过同一出口抓取站点的入口页面,保留入口页面分配的 cookie,并携带这些 cookie 再次请求你的目标 URL。这就是 warmup 阶梯。它仅在 URL 深于站点根目录且直接尝试已失败时触发,并且只会增加成功机会,绝不会导致现有结果失效。
forceProxy 默认为 true,因此阶梯 1 和 2 会被跳过,目标站点永远不会看到 FourA 的自有地址。多数调用随后会在阶梯 3 完成,或通过重放已建立的预热会话完成。当你明确知道目标站点对纯净地址的接纳度优于轮换地址时,可设置 forceProxy: false,阶梯 1 和 2 便会重新启用。
请求参数
最基本的要求是提供一个 URL 以及一个 validate 子字符串。Auto 本身能识别常见的质询页面,但如果没有 validate.data.accept,它无法区分真实页面与未知的校验页面,也无法识别未加载目标内容的页面,并可能将两者误判为成功。
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"]}}
}'
可选配置项(完整详情请参阅 endpoint 参考):
returnSession(默认true):返回胜出的{ proxy, cookies, userAgent },便于后续重放。forceProxy(默认true):跳过直连出口阶梯。仅当您确定目标站点对纯净 IP 比对轮换出口更友好时,才设为false。timeout_ms(默认120000):整个调用的总预算时间。阶梯策略会将其分配到各个阶段。ignoreProxies:在每次子尝试中需避开的 proxy ID。followRedirects(默认5):低成本阶梯上的最大重定向次数。headers:发送给站点的 headers,格式为[name, value]键值对。它们会在 Single 和 Proxy request 中发出(包括寻找有效出口的过程),浏览器阶梯则不会发送。您自带的Cookie会原样传达至站点,预热 session 的 cookies 仅会在您未发送同名 cookie 时补充添加。当预热 session 包含userAgent时,它会替换您的User-Agent。诸如If-None-Match和If-Modified-Since等条件 header 在出口搜索阶段会被忽略,除非您的validate.status.accept包含304。exitClass:premium允许 Auto 在标准池无法访问页面时升级至高级出口;standard则表示绝不升级。需要包含高级出口的套餐支持。请参阅 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与data:目标的响应内容。无论由哪一阶梯层提供页面,data均为文本,因此 JSON 页面会以 JSON 文本形式返回,需自行解析。status是目标的 HTTP 状态码,而非调用 FourA 的传输层状态。对于 single 和 proxy 阶梯层,headers是逐跳数组。对于 browser 阶梯层,headers是扁平对象。meta:阶梯运行追踪信息,阶梯启动后的每个响应中都会包含。meta.rung指明交付响应的步骤,meta.attempts统计子调用重试次数,meta.solved标记是否完成了验证页面,meta.credits是该次调用的总消耗(与X-FourA-Credits响应头数值相同)。meta.attemptsByEngine与meta.browserRequests说明了该调用消耗的项目:参见 调用消耗说明。当请求指定了exitClass时,meta.exitClass会指明实际交付的出口类别。session:成功破解目标的{ proxy, cookies, userAgent }三元组。可用于通过/api/single/或/api/browser/对同一主机重放请求。字段可能会缺失:通过普通 proxy 抓取获得的会话包含proxy但没有userAgent,且其cookies列表仅包含站点在提供页面前由验证页设置的 cookie,因此通常为空。仅当此类验证页设置了 cookie 时,来自低成本 direct 探测的响应才会携带session,且此时仅包含cookies。由出口返回且属于validate.status.accept列表中的状态码(例如已删除页面的404)完全不会包含session。
只要阶梯运行过,即使所有阶梯层均失败,Auto 也会返回 HTTP 200。请查看响应体中的 status 和 error 以获取实际执行情况,而不是查看传输层状态码。/api/auto/ 返回非 200 意味着调用根本未到达阶梯:401 表示密钥无效;400 表示请求体不是合法 JSON、目标处于专用网络、目标属于 FourA 自身的 API 主机,或 URL 中包含未编码的空格;403 带有 X-FourA-Limit: plan_limit_premium 表示套餐不支持高级出口却使用了 exitClass: premium;502、503 或 504 表示服务无法接收调用或已超时。Auto 在网关处不占用槽位,因此平台的共享限制不会拒绝调用本身:当共享限制拒绝阶梯发起的调用时,响应为 HTTP 200,且响应体中包含 status: 429 或 503 以及 retryAfter。验证失败的字段也会以 HTTP 200 返回,并带有 status: 400。在阶梯内部触发套餐限制同样返回 HTTP 200,拒绝原因包含在响应体中(参见 套餐限制与阶梯冲突说明)。
使用会话重放
Auto 返回会话后,针对同一主机的后续页面,可以直接进入 Single 或 Browser。无需重新爬升阶梯,无需重新探测。
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.get("session") or {}
proxy = session.get("proxy")
user_agent = session.get("userAgent")
# 2) Follow-up pages: replay through single with the same proxy, UA and cookies.
for sku in ("43", "44", "45"):
body = {"method": "GET", "url": f"https://example.com/product/{sku}"}
if proxy:
body["proxy"] = proxy
headers = []
if user_agent:
headers.append(["User-Agent", user_agent])
if session.get("cookies"):
headers.append(["Cookie", "; ".join(f"{c['name']}={c['value']}" for c in session["cookies"])])
if headers:
body["headers"] = headers
r = requests.post(f"{API}/api/single/", headers=H, json=body).json()
print(sku, r["status"])
会话的有效时长完全取决于目标网站的设置。某些网站的通行凭证在 cookie jar 中可持续数小时,而另一些网站每隔几分钟就会轮换一次。如果重放请求再次开始返回质询,请再次调用 /api/auto/ 进行刷新。
何时使用 Auto
| 使用 auto | 手动使用 single、proxy 或 browser |
|---|---|
| 目标是新网站,尚不清楚其具体要求 | 已经明确可行的执行引擎 |
| 希望通过单次调用自动处理 proxy 和 browser 回退 | 需要完全控制每次调用的重试和超时配置 |
| 可以接受首次调用耗费数秒进行探测 | 首次调用延迟比自动探测更重要 |
| 需要获取可低成本重放的学习会话 | 正在针对已知可行的目标优化高频循环 |
Auto 并不总是成本最低的选择。如果已知目标支持 single + unblocker,直接调用 Single 只需 2 个点数且延迟可控。针对同一目标使用 Auto 则会消耗其梯度探测所需的点数,若目标网站需要逐步提权,成本可能会更高。
Validate 告知 Auto 何为“成功”
最重要的参数是 validate。若未配置该参数,auto 仅会拒绝其能够识别的质询页面,导致未知的检测页面或带有 HTTP 200 状态码的空外壳被误判为有效内容。
配合 validate.data.accept 使用仅在真实页面中存在的子字符串:
{
"validate": {
"data": {
"accept": ["sku-42-add-to-cart", "Customer reviews"]
}
}
}
对于 JSON API,接收预期的字段名称:
{
"validate": {
"data": { "accept": ["\"products\":["] },
"status": { "accept": [200] }
}
}
对于合理返回非 200 的站点(您希望忽略的地区限制、已删除页面的 404 或 410),可以通过 validate.status.accept 允许它们:
{
"validate": {
"status": { "accept": [200, 451] }
}
}
一旦某个出口返回了您在 validate.status.accept 中列出的状态码,并且该结果通过了您规则中的其余检查,Auto 就会立即返回该状态码。但有四个状态码例外:202、403、429 和 503。Auto 会将这些状态码视作目标站点正在校验请求者身份,因此返回这些状态码的出口不会终止搜索,阶梯会继续向上攀升。
如果没有配置 validate,对于所有未识别为质询的页面,Auto 会默认回退至“HTTP 200 = 成功”逻辑,因此无法捕获站点以 200 状态码返回的不熟悉检测页面。
读取 meta.rung 以了解具体发生的情况
meta.rung 是最有价值的调试信号。具体取值如下:
probe:通过低成本的 direct 请求解决。成本最低的路径。proxy:需要通过 proxy 轮换才能通过。browser:需要完整的浏览器渲染,可能还包含质询破解。cache:复用了之前 auto 调用的预热 session。重复调用时的最低成本路径。warmup:站点正常提供了入口页面,但对深层 URL 进行了拦截,因此 auto 先获取了入口页面,保留其下发的 cookie,并携带这些 cookie 重新发起请求。此阶梯保存的 session 不与单个出口绑定,因此后续调用可直接命中低成本阶梯。fail:没有阶梯生成符合您规则的响应。
meta.solved: true 表示调用期间遇到并完成了质询页面。meta.attempts 是成功前子调用的重试次数。如需了解其背后的详细信息,请查看 single 和 proxy 阶梯返回的 defense 字段:参见 站点检查。
如果您预期应命中 probe,但站点始终停留在 browser,请考虑调整 validate 规则(调严格或放宽),以允许更低成本的阶梯通过。请注意,forceProxy 默认为 true,因此除非您手动将其关闭,否则将跳过直连出口探测。
调用消耗明细
meta.attemptsByEngine 统计了本次调用向各个引擎发送的 request 数量,这与 Overview 页面中 Auto attempts 面板显示的数据一致。meta.browserRequests 统计了消耗每日浏览器配额的请求数量。
"meta": {
"rung": "browser",
"solved": true,
"attempts": 7,
"credits": 47,
"attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
"browserRequests": 2
}
| 字段 | 类型 | 说明 |
|---|---|---|
meta.attemptsByEngine |
object | 发送到 single、proxy 和 browser 的 request。因计划限制而被拒绝的浏览器 request 也会计入此处,因为该 request 已发出。 |
meta.browserRequests |
number | 消耗了每日配额槽位的浏览器 request。因计划限制而被拒绝的浏览器 request 不消耗配额。 |
meta.attempts 统计的是梯级步骤数,因此并不总是等于 meta.attemptsByEngine 的总和。一个步骤可能会先后发送一个 Single request 和一个 Proxy request,而若某一步骤的浏览器当天配额已耗尽关闭,则不会发送任何内容。
当天的累计计数通过 X-FourA-Browser-Used-Today 和 X-FourA-Browser-Limit-Per-Day header 传递:参见 Response Headers。
错误与边缘情况
当 auto 失败时,response 会携带 status(通常是最后一个失败阶梯的状态)和一个 error 字符串:
{
"status": 502,
"error": "could not find a working exit for the target",
"attempts": 7,
"attemptReport": {
"total": 7,
"noResponse": 5,
"defense": 2,
"contentRejected": 0,
"statusRejected": 0,
"other": 0,
"vendors": ["datadome"],
"summary": "7 attempt(s): 5 got no answer from the site; 2 refused by the site (datadome)"
},
"meta": {
"rung": "fail",
"solved": false,
"attempts": 7,
"credits": 47,
"attemptsByEngine": {"single": 0, "proxy": 4, "browser": 3},
"browserRequests": 3
}
}
status 是目标站点在最后一次尝试中被 Auto 拒绝时的响应,例如 403。当所有尝试均未从站点获取任何响应时,通常返回 502 或 504,并且 error 会指明是未找到可用出口还是耗尽了 timeout_ms 预算。status: 0 仅表示目标主机名无法解析,该响应不包含 meta,因为梯级尝试从未启动。
当浏览器持续遇到无法完成的验证时,Auto 也会提前终止。在两个出口均以该方式拒绝浏览器,且搜索通过 validate 规则的普通抓取出口无结果后,或者累计出现三次此类出口拒绝后,调用即告结束。status 包含站点的最后一次响应,error 以 the browser was refused by 开头,后跟验证系统的名称。
当站点本身表明页面不存在时,Auto 也会停止尝试。当两个出口返回相同的 404 或 410 且您的规则不接受该状态时,调用以该 status 结束,且 error 以 the site answered 开头。如果您需要已被移除页面的响应,请在 validate.status.accept 中列出 404 或 410:这样只要出口返回该状态,Auto 就会直接将其作为交付结果返回。
在使用您的 API key 连续 4 次 Auto 调用因站点持续拒绝而未能获取页面后,Auto 将暂停该 key 对该站点的请求 120 秒。在此期间发起的调用会立即返回 status: 503、error: "target temporarily unservable, retry later" 以及以秒为单位的 retryAfter,且不产生任何费用。该计数按 API key 单独计算:调用同一站点的其他 key 不受影响,且任何成功获取页面的调用都会重置计数。带有 exitClass: premium 的调用不受此限制。
检查 attemptReport、meta.attemptsByEngine 和 meta.credits 可查看预算消耗情况。如果 meta.attempts 较高,且浏览器梯级后 meta.rung 为 fail,则目标可能需要更长的 timeout_ms、更严格的 validate 规则,或者当前根本无法通过轮换代理访问。
Auto 调用失败的原因
已运行梯级返回的每个失败响应均包含 attemptReport。它会根据所遇到的情况,对未成功返回页面的引擎请求进行单次分类计数。
| 字段 | 类型 | 说明 |
|---|---|---|
total |
integer | 未返回页面的 request 数量。至多为 meta.attemptsByEngine 的总和,因为因套餐配额限制而拒绝的 browser request 从未尝试请求目标网站。 |
noResponse |
integer | 未收到目标网站的响应 |
defense |
integer | 目标网站拒绝了 request:识别出 Bot 验证、页面包含质询,或目标网站返回了 401、403、429 或 503 |
contentRejected |
integer | 页面已成功抓取,仅因触发了您的 validate 规则而被拒绝 |
statusRejected |
integer | 目标网站返回了您的 request 不接受的状态码,例如页面已删除返回的 404 |
other |
integer | 因其他原因失败,例如服务器错误 |
vendors |
string[] | 调用过程中遇到的拒绝响应里所识别出的 Bot 验证供应商 |
summary |
string | 根据各项计数生成的一句话摘要,适合直接记录到日志中。如果未识别出任何供应商,它会指明目标网站返回的 HTTP 状态码;同时在每日 browser 配额耗尽导致无法启动 browser 时给出提示。 |
这些字段与失败的 Proxy 调用报告一致,只是不包含 profilesTried。两者的区别有两点:Proxy 统计其尝试过的每个出口节点数量,上限为您设置的 maxTries;而 Auto 统计的是其自身发起的 request 数量。此外,Auto 还会解析页面内容及其状态码,因此即使未识别出具体供应商,拒绝行为也会计入 defense。contentRejected 中的计数项是您可以自行修复的:页面已成功返回,但未能匹配您预设的规则。
当套餐限制遇到梯度回退机制时
Auto 的子调用是在您的 API key 下发起的普通 Single、Proxy 和 Browser request,因此受您的 套餐限制约束。梯度回退机制会读取拒绝响应中的 X-FourA-Limit 代码,并将这两类情况区别对待。
某个梯度层级关闭后,其余层级仍可继续使用。 plan_limit_browser_daily(当天 Browser request 配额已用尽)和 plan_limit_concurrency(该 endpoint 当前并发运行的 request 已达到套餐上限)只会关闭单个层级。Auto 会继续在其余层级上执行,因此只要轮换出口节点或预热 session 能够提供内容,您仍然可以获取页面;系统也不会把因自身套餐限制导致的拒绝归咎于已尝试的出口节点。任何节点都不会被封禁,session 也不会被废弃。
账户耗尽则直接终止梯度回退。 plan_limit_credits、plan_limit_bandwidth、plan_limit_rate、plan_limit_feature 和 plan_limit_premium 无法通过切换其他层级来解决,因此 Auto 会立即返回,而不会继续消耗您的点数去重复验证。拒绝详情将在 body 中返回,包含子调用的状态码以及直接调用 endpoint 时返回的相同 reason 字段:
{
"status": 429,
"error": "Credit limit reached: 300,000 of 300,000 credits used this billing period. Upgrade your plan or wait for the reset.",
"reason": "plan_limit_credits",
"documentation": "https://foura.ai/prices",
"used": 300000,
"hard_stop": 300000,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z",
"meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
来自子调用的完整拒绝 body 会透传返回,外加 status、attemptReport 和 meta。请从 body 中读取 status,而不是从传输层状态中读取:此处 auto 仍会返回 HTTP 200,因为阶梯回退已执行。plan_limit_feature 或 plan_limit_premium 的拒绝也会以相同方式伴随 status: 403 返回。被拒绝的子调用不会消耗任何费用,因此 meta.credits 仅计算实际到达目标的阶梯层级。
单个 auto 调用在阶梯爬升时可能会占用多个槽位,因此并发的一批 auto 调用达到并发上限所需的调用量会比你预期的更少。并行运行请求介绍了批次大小的调整方法。
Auto 不具备的功能
- 它不会改变法律限制。如果某个网站拒绝了 FourA 能访问的所有出口,auto 会直接返回该拒绝。
- 它不缓存内容。每次调用仍会直接请求目标。所谓“预热会话”指的是 proxy 和 cookie,而非 response。
- 它在 活动日志中表现为单行记录,归于你收到的 request ID 下,并汇总其子调用的 credit 消耗。展开该记录后,auto 代你发起的 Single、Proxy、Browser 子调用会作为尝试次数列出,每项均有各自的处理结果。它们计入你的 Single、Proxy 和 Browser 配额限制,绝不会计入你的 request 计数或成功率统计。
相关内容
- API Endpoints:完整参数参考
- 选择合适的 Endpoint:何时在 auto 与 single、proxy 或 browser 之间进行选择
- 请求结果:哪些结果属于计费范围
- 受保护的网站:FourA 在遇到检测访问者身份的网站时的处理机制
- 站点检测:
meta.solved背后的defense字段 - MCP 操作方案:对应 MCP 工具调用的相同模式
- 速率限制:衡量 auto 子调用所依据的套餐限额