# 智能获取 (Auto)

> URL: https://foura.ai/zh/docs/guides/smart-fetch
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

你向 FourA 提供一个 URL 和一条关于真实页面应包含内容的 `validate` 规则。其余工作由 FourA 完成：它按成本效益阶梯逐步尝试，停在首个返回满足你规则的响应阶梯上，并按主机记录有效策略，使同一站点的下一次调用成本更低。

本指南介绍 auto 的底层运行机制、适用场景以及如何解析其响应。有关参数参考，请参阅 [API Endpoints](https://foura.ai/docs/api/endpoints#smart-fetch-auto)。

## 核心概念

大多数抓取方案要求你预先指定引擎。Single 最快，Proxy 提供轮换，Browser 负责处理 JavaScript。一旦预判错误，就会浪费积分或遭遇拦截。

Auto 改变了这种模式。你只需定义成功标准（`validate`），无需指定实现方式。FourA 依次尝试不同阶梯，直到某一阶梯成功：

1. **低成本探测**（single，直接来自 FourA 自有网络）
2. **Browser**，直接来自 FourA 自有网络，支持 JavaScript，并在站点发起质询时调用求解器
3. **轮换 proxy single**
4. **通过 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`，它无法区分真实页面与未知的校验页面，也无法识别未加载目标内容的页面，并可能将两者误判为成功。

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

可选配置项（完整详情请参阅 [endpoint 参考](https://foura.ai/docs/api/endpoints#smart-fetch-auto)）：

- `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](https://foura.ai/docs/api/endpoints#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` 与 `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` 说明了该调用消耗的项目：参见 [调用消耗说明](#what-a-call-spent)。当请求指定了 `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，拒绝原因包含在响应体中（参见 [套餐限制与阶梯冲突说明](#when-your-plans-limits-meet-the-ladder)）。

## 使用会话重放

Auto 返回会话后，针对同一主机的后续页面，可以直接进入 Single 或 Browser。无需重新爬升阶梯，无需重新探测。

```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.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` 使用仅在真实页面中存在的子字符串：

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

对于 JSON API，接收预期的字段名称：

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

对于合理返回非 200 的站点（您希望忽略的地区限制、已删除页面的 `404` 或 `410`），可以通过 `validate.status.accept` 允许它们：

```json
{
  "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` 字段：参见 [站点检查](https://foura.ai/docs/api/site-checks)。

如果您预期应命中 `probe`，但站点始终停留在 `browser`，请考虑调整 `validate` 规则（调严格或放宽），以允许更低成本的阶梯通过。请注意，`forceProxy` 默认为 `true`，因此除非您手动将其关闭，否则将跳过直连出口探测。

## 调用消耗明细

`meta.attemptsByEngine` 统计了本次调用向各个引擎发送的 request 数量，这与 [Overview](https://foura.ai/docs/dashboard/overview) 页面中 Auto attempts 面板显示的数据一致。`meta.browserRequests` 统计了消耗每日浏览器配额的请求数量。

```json
"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](https://foura.ai/docs/api/response-headers)。

## 错误与边缘情况

当 auto 失败时，response 会携带 `status`（通常是最后一个失败阶梯的状态）和一个 `error` 字符串：

```json
{
  "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 调用](https://foura.ai/docs/troubleshooting/proxy-attempt-report)报告一致，只是不包含 `profilesTried`。两者的区别有两点：Proxy 统计其尝试过的每个出口节点数量，上限为您设置的 `maxTries`；而 Auto 统计的是其自身发起的 request 数量。此外，Auto 还会解析页面内容及其状态码，因此即使未识别出具体供应商，拒绝行为也会计入 `defense`。`contentRejected` 中的计数项是您可以自行修复的：页面已成功返回，但未能匹配您预设的规则。

### 当套餐限制遇到梯度回退机制时

Auto 的子调用是在您的 API key 下发起的普通 Single、Proxy 和 Browser request，因此受您的 [套餐限制](https://foura.ai/docs/api/rate-limits)约束。梯度回退机制会读取拒绝响应中的 `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` 字段：

```json
{
  "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 调用达到并发上限所需的调用量会比你预期的更少。[并行运行请求](https://foura.ai/docs/how-to/run-requests-in-parallel)介绍了批次大小的调整方法。

## Auto 不具备的功能

- 它不会改变法律限制。如果某个网站拒绝了 FourA 能访问的所有出口，auto 会直接返回该拒绝。
- 它不缓存内容。每次调用仍会直接请求目标。所谓“预热会话”指的是 proxy 和 cookie，而非 response。
- 它在 [活动日志](https://foura.ai/docs/dashboard/activity-log)中表现为单行记录，归于你收到的 request ID 下，并汇总其子调用的 credit 消耗。展开该记录后，auto 代你发起的 Single、Proxy、Browser 子调用会作为尝试次数列出，每项均有各自的处理结果。它们计入你的 Single、Proxy 和 Browser 配额限制，绝不会计入你的 request 计数或成功率统计。

## 相关内容

- [API Endpoints](https://foura.ai/docs/api/endpoints#smart-fetch-auto)：完整参数参考
- [选择合适的 Endpoint](https://foura.ai/docs/guides/choosing-task-type)：何时在 auto 与 single、proxy 或 browser 之间进行选择
- [请求结果](https://foura.ai/docs/api/outcomes)：哪些结果属于计费范围
- [受保护的网站](https://foura.ai/docs/guides/protected-sites)：FourA 在遇到检测访问者身份的网站时的处理机制
- [站点检测](https://foura.ai/docs/api/site-checks)：`meta.solved` 背后的 `defense` 字段
- [MCP 操作方案](https://foura.ai/docs/mcp/recipes)：对应 MCP 工具调用的相同模式
- [速率限制](https://foura.ai/docs/api/rate-limits)：衡量 auto 子调用所依据的套餐限额
