API 端点参考

包含所有 FourA API endpoint 的参考，包括请求参数和响应格式。

基础 URL

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

身份验证

每个请求都需要在 X-API-Key header 中包含您的 API 密钥：

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/* 的 response 包含两个关联 header：

Header	值	描述
`X-FourA-Request-Id`	UUID	分配给 request 的唯一 ID。在每次 response 中返回，包括 4xx 和 5xx。请在您的系统中记录它。
`X-FourA-Credits`	整数	此 request 消耗的积分。成功和失败时均会返回(两种情况都已执行工作)。有关哪些结果计费的信息，请参见 Request Outcomes。

相同的 request ID 会在控制台的 Activity Log(保留 24 小时，每个密钥保留最近 200 条记录)中关联 request 和 response payload 预览，以便您稍后查找确切的 request，并直接从 Activity 重放到 Playground 中。联系支持团队时请提供此 ID，以便在几秒钟内准确定位该 request。

$ 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 server 将所有四个端点包装为原生 MCP 工具 (foura_auto, foura_single, foura_proxy, foura_browser)，具有相同的输入结构，外加一个对 token 友好的大型 response 处理 offload_large 选项。

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

端点	适用场景
`POST /auto/`	智能获取 (Smart fetch)。您传递一个 URL，FourA 会选择最便宜且有效的路径 (直连、轮换 proxy 或浏览器)，并记住每个主机的有效方式。
`POST /single/`	快速 HTTP request、静态页面、API
`POST /proxy/`	受保护的站点，带有自动 proxy 轮换和可选的目标可见国家或地区范围限制
`POST /browser/`	JavaScript 渲染的页面、SPA
`GET /profiles`	用于 `single` 和 `proxy` 的浏览器配置文件目录。公开，不需要 API 密钥。

有关何时选择各个端点的深入探讨，请参阅选择合适的端点 (Choosing the Right Endpoint) 和智能获取指南 (Smart Fetch guide)。

目标 URL 限制

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

{ "error": "Target <ip> resolves to a private/reserved IP" }

智能获取 (Auto)

POST /api/auto/

您传入 URL 及可选的 validate 规则。FourA 会遍历成本感知的阶梯（廉价直接探测、轮换 proxy、完整浏览器），并在返回符合您规则的 response 的第一阶停止。在对同一主机的重复调用中，会重放预热好的 session，因此第二次请求成本很低。

您无需调整重试次数、池大小或 proxy 数量。FourA 会针对每个主机进行学习。

请求体

参数	类型	必填	默认值	描述
`url`	string	是	-	目标 URL
`method`	string	否	`"GET"`	HTTP 方法
`headers`	[string, string][]	否	-	自定义 header，格式为 [name, value] 键值对
`data`	any	否	-	非 GET 请求的请求体
`validate`	object	否	-	成功标准，结构与单次请求的 `validate` 相同（见下文）。告知 auto 真实的页面是什么样，以便它区分内容页面和质询页面。
`returnSession`	boolean	否	`true`	在 response 中包含成功的 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/` response 返回的 ID。
`followRedirects`	integer	否	`5`	在廉价阶梯层级上允许跟随的最大重定向次数。设为 `0` 以禁用。最大值为 `20`。

响应

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

字段	类型	说明
`status`	number	目标返回的 HTTP 状态。
`data`	string 或 object	响应体。
`headers`	array 或 object	目标响应 header。Single 和 proxy 层级返回每次跳转的 header 对象数组，browser 层级返回扁平对象。
`meta.rung`	string	传递响应的梯级。可选值：`probe`（低成本直接 request），`proxy`（轮换 proxy），`browser`（完整浏览器渲染），`cache`（重放预热会话），或 `fail`（没有梯级生成被接受的响应）。
`meta.solved`	boolean	是否在此次调用期间解决了机器人验证挑战。
`meta.attempts`	number	成功前进行的子尝试次数。
`meta.credits`	number	此次调用花费的总积分。与 `X-FourA-Credits` 匹配。
`session.proxy`	string	传递响应的 proxy 的编码 ID。可在 Single 或 Browser request 中复用。当 `returnSession` 为 `true` 时存在。
`session.cookies`	array	成功尝试中的 cookie。当 `returnSession` 为 `true` 时存在。
`session.userAgent`	string	成功尝试中使用的 User-Agent。当 `returnSession` 为 `true` 时存在。
`error`	string	调用失败时的错误消息。

示例

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 密钥转发给每个子调用。每个子调用都会显示在您的 Activity Log 中；外部的 /api/auto/ 调用不会增加单独的计费行。
传递仅真实页面包含的子字符串给 validate.data.accept。如果没有它，Auto 无法区分真实的 200 响应和返回状态码为 200 的质询插页。
timeout_ms 限制整个调用的时间。首次冷访问受保护站点可能需要几十秒；重用的热会话通常在不到一秒内完成。

Single 请求

POST /api/single/

发送具有逼真浏览器网络特征的 HTTP 请求，无需启动真实的浏览器。这是最快的 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` 以发送普通的客户端签名。
`timeout_ms`	number	否	15000	总超时时间，单位 ms (最大值: 120000)
`connect_timeout_ms`	number	否	5000	连接超时时间，单位 ms
`accept_timeout_ms`	number	否	5000	接受超时时间，单位 ms (等待连接被接受的时间)
`server_response_timeout_ms`	number	否	15000	服务器响应超时时间，单位 ms (等待首字节的时间)
`dns_cache_timeout_sec`	number	否	120	DNS 缓存 TTL，单位秒 (最大值: 240)
`followRedirects`	number	否	disabled	允许跟随的最大重定向次数 (0-20)。省略则禁用。
`tryJsonData`	boolean	否	false	尽可能将 response body 解析为 JSON
`returnBuffer`	boolean	否	false	返回原始 buffer 而不是解码后的 string
`data`	any	否	-	Request body (string 或 object，自动序列化为 JSON)
`proxy`	string	否	-	来自先前 response 的 proxy ID，用于固定相同的出口。原样传回不透明的 string。原始 proxy 地址会被拒绝并返回 `400 Invalid proxy format`。
`browser`	string	否	Chrome	呈现的浏览器: Chrome, Edge, Safari, Firefox, 或 Tor。请参阅浏览器配置文件。
`os`	string	否	-	呈现的操作系统: Windows, macOS, Android, 或 iOS。系统系列名称接受其任何版本。
`version`	string	否	newest	呈现的浏览器版本，如目录所列。当有多个匹配项时，选择最新的版本。
`profile`	string	否	-	来自 `GET /api/profiles` 的精确配置文件 id，替代上述三个字段。
`validate`	object	否	-	Response 验证规则 (见下文)

浏览器配置文件

默认情况下，request 会呈现最新的 Google Chrome。某些目标接受特定浏览器而拒绝其他浏览器，因此 browser, os, 和 version 用于缩小已测量配置文件的目录范围，而 profile 通过 id 选择其中一个。

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

规则：

选择需要 unblocker (默认开启)。在 unblocker 关闭的情况下，不会发送浏览器 headers，因此 request 会被直接拒绝，而不会被部分应用。
当有多个配置文件匹配时，采用最新版本。
目录中无法提供的组合会返回错误，并列出可用选项。request 绝不会以其他浏览器的身份发送。
在 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	必须存在的 header 键值对
`validate.headers.fail`	object	会触发失败的 header 键值对
`validate.data.accept`	string[]	响应体中必须出现的字符串
`validate.data.fail`	string[]	响应体中会触发失败的字符串

示例

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

响应：

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342,
  "proxy": "A1B2C3"
}

当目标在获取正文的过程中执行 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	每个重定向跳转对应一个对象。每个对象包含一个 `result` 字段，提供状态行及所有响应 header。多值 header (`Set-Cookie`, `Link`, `WWW-Authenticate`) 会作为字符串数组返回。
`data`	string/object	响应体 (如果 `tryJsonData` 为 true，则为 JSON)
`total_time`	number	总请求时间 (秒)
`proxy`	string	请求所经过 proxy 的编码 ID (仅在请求中提供了 `proxy` 时出现)。在后续调用中重用此 ID 可固定同一出口。
`defense`	object	仅在目标对此请求执行了机器验证时出现。`defense.solved` 表示是否通过了验证。有关所有字段和完整供应商列表，请参阅反爬虫防御。
`error`	string	请求失败时的错误信息

Proxy 请求

POST /api/proxy/

通过轮换 proxy 路由您的请求，并在失败时自动重试。可以选择将选择范围限制在一组目标可见的出口国家。

请求体

参数	类型	必填	默认值	描述
`request`	object	是	-	单个请求体 (字段与上述的 Single Request 相同)
`timeout_ms`	number	否	45000	所有尝试的总超时时间 (毫秒) (最大值: 120000)
`maxTries`	number	否	5	最大 proxy 轮换尝试次数 (最大值: 90)
`ignoreProxies`	string[]	否	-	要从轮换中排除的 proxy ID (使用先前响应返回的 ID)
`exitCountries`	string[]	否	-	目标可见的双字母国家代码的严格白名单 (例如 `["CZ", "GB"]`)。值会被去除空格、转换为大写并去重。未知出口的 proxy 将被排除，请求绝不会降级使用未请求的国家。

exitCountries 范围设定

选择过程使用最新可用的目标可见国家元数据，通常约十分钟刷新一次。这并非在请求期间的实时地理位置查询。请勿从 proxy 主机地址推断服务国家。

如果当前池没有与请求国家匹配的项，响应将返回 HTTP 200 及错误包装层：

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

保留请求的范围并稍后重试。仅当工作流的国家/地区要求明确改变时，才更改或扩大该范围。

示例

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

响应：

{
  "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 的编码标识符。通过将其作为 `proxy` 字段传递，在 Single 或 Browser request 中重用它，或者在下一次 Proxy request 中通过 `ignoreProxies` 跳过它。
`exitCountry`	string	处理该 request 的 proxy 对目标可见的双字母国家/地区代码。仅当 request 设置了 `exitCountries` 时才存在。在信任 response 之前，请始终验证它是您请求的代码之一。
`total`	number	外部挂钟耗时，以秒为单位(浮点数)。包含 proxy 选择、重试和成功尝试的耗时。`total_time` 仅表示内部 request；`total` 始终 >= `total_time`。
`error`	string	如果 request 失败，则显示错误消息。在作用域未命中时，`code` 为 `no_eligible_proxy` 且 `details.exitCountries` 回显标准化的作用域。

所有 Single Request response 字段也都包含在内，包括 defense:遭遇 bot 检查的 proxy 尝试会像 Single 一样报告它。

Browser Request

POST /api/browser/

在一个 Chrome 浏览器实例中打开您的 URL。页面加载，JavaScript 执行，您将获得完全渲染的 HTML 加上 cookie 集合。

Request Body

参数	类型	是否必需	默认值	说明
`url`	string	是	-	目标 URL
`headers`	object	否	-	自定义 header 键值对
`cookies`	array	否	-	要设置的 cookie: `[{name, value, domain?}]`
`userAgent`	string	否	-	自定义 User-Agent 字符串
`unblocker`	boolean	否	`true`	在页面加载期间自动解决常见的 bot 质询(Cloudflare 验证，类似的网关)。默认开启。设置为 `false` 则原样渲染页面返回的任何内容，包括质询页面，而不进行求解。
`proxy`	string	否	-	来自早期 response 的 proxy ID，用于固定相同的出口。原样传回不透明的字符串。原始 proxy 地址会被拒绝，返回 `400 Invalid proxy format`。
`timeout_ms`	number	否	30000	页面加载超时，单位毫秒 (最大值: 120000)
`checkStatus`	number	否	-	预期的 HTTP 状态 (如果不同则 request 失败)
`checkText`	string	否	-	渲染后的页面中必须出现的文本

示例

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

响应:

{
  "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"]},
  "proxy": "A1B2C3"
}

字段	类型	描述
`status`	number	来自目标网站的 HTTP 状态码
`headers`	object	响应头
`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`。否则不存在。这决定了消耗 15 还是 30 个积分。
`defenses`	object	`present` 列出了页面加载期间识别到的所有供应商，`cleared` 列出了最终页面拥有其放行凭证的供应商。一个供应商可能出现在 `present` 中而从未出现在 `cleared` 中。请参阅反机器人防御。
`proxy`	string	请求所经过 proxy 的编码 ID(仅当请求中提供了 `proxy` 时)。在后续调用中重用它以保持相同的出口。
`error`	string	请求失败时的错误信息

HTTP 状态码

状态码	含义
200	请求已完成(检查内部 `status` 以获取目标响应)
400	无效的请求体、参数，或目标 IP 位于私有/保留地址段
401	缺失或无效的 API 密钥
429	超出速率限制
500	内部服务器错误
502	`Upstream unavailable`。FourA 已到达其引擎但回复不可用。请重试。
503	服务暂时不可用或已满载，或者在引擎重启时出现 `Backend service unavailable`
504	`Upstream timeout`。引擎未能在本次请求的时间预算内完成。请提高 `timeout_ms` 或重试。

后续步骤

智能抓取(自动): 何时让 FourA 为您选择路径
选择正确的 endpoint: 何时手动选择 Single、Proxy 或 Browser
身份验证: 管理您的 API 密钥
错误处理: 优雅地处理错误
反机器人防御: 读取 defense 字段并重放凭证
速率限制: 了解请求限制
快速入门: 30 秒内完成首次请求

更新于： 2026年8月12日