Tài liệu › Tham chiếu API › Tham chiếu API Endpoints

Tham chiếu API Endpoints

Tài liệu tham khảo cho tất cả các endpoint của FourA API với các tham số request và định dạng response.

Base URL

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

Xác thực

Mọi request đều yêu cầu API key của bạn trong header X-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"}'

Tạo và quản lý các API keys trong Dashboard. Các keys sử dụng tiền tố pk_live_.

Các Response Headers

Mọi response từ /api/* đều mang hai headers tương quan:

Header Value Mô tả
X-FourA-Request-Id UUID ID duy nhất được gán cho request. Được trả về trên mọi response, bao gồm cả 4xx và 5xx. Hãy ghi log ID này ở phía bạn.
X-FourA-Credits integer Số credit đã tiêu tốn cho request này. Được trả về khi thành công và khi thất bại (công việc đã được thực hiện trong cả hai trường hợp). Xem Kết quả Request để biết các kết quả nào bị tính phí.

Cùng một request ID đó liên kết các bản xem trước payload của request và response trong Activity Log của Dashboard (được giữ trong 24 giờ, 200 bản ghi gần nhất cho mỗi key), nhờ đó bạn có thể tra cứu request chính xác sau này và phát lại nó từ Activity thẳng vào Playground. Hãy cung cấp ID này khi bạn liên hệ với bộ phận hỗ trợ, và nó sẽ giúp xác định chính xác request trong vài giây.

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

Xem Response Headers để biết danh sách đầy đủ và mẹo sử dụng.

Endpoints

Sử dụng các endpoint này qua MCP? @fouradata/mcp server bao bọc cả bốn endpoint dưới dạng các công cụ MCP gốc (foura_auto, foura_single, foura_proxy, foura_browser) với cùng định dạng đầu vào cộng với tùy chọn offload_large để xử lý response lớn thân thiện với token.

FourA cung cấp bốn request endpoint, mỗi endpoint được tối ưu hóa cho một kịch bản khác nhau:

Endpoint Tốt nhất cho
POST /auto/ Smart fetch. Bạn truyền vào một URL, FourA chọn đường dẫn rẻ nhất hoạt động được (trực tiếp, proxy luân phiên hoặc trình duyệt) và ghi nhớ cấu hình hoạt động cho từng host.
POST /single/ HTTP request nhanh, trang tĩnh, API
POST /proxy/ Các trang được bảo vệ với luân phiên proxy tự động, tùy chọn giới hạn quốc gia hiển thị với mục tiêu
POST /browser/ Các trang render bằng JavaScript, SPA
GET /profiles Danh mục browser-profile cho single và proxy. Công khai, không cần API key.

Để xem chi tiết hơn về thời điểm chọn từng endpoint, hãy xem Choosing the Right Endpoint và Smart Fetch guide.

Các hạn chế của Target URL

Các mục tiêu phân giải thành các dải IP private, loopback hoặc reserved (RFC 5735, RFC 6598, IPv6 reserved blocks) sẽ bị từ chối bằng lỗi 400 trước khi request rời khỏi FourA. Chỉ các hostname và IP công khai mới được chuyển tiếp.

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

Smart Fetch (Auto)

POST /api/auto/

Bạn truyền một URL cùng với các quy tắc validate tùy chọn. FourA thực hiện một chuỗi tối ưu chi phí (thử nghiệm trực tiếp giá rẻ, proxy xoay vòng, trình duyệt đầy đủ) và dừng lại ở bước đầu tiên trả về response mà các quy tắc của bạn chấp nhận. Khi gọi lại cùng một host, một session đã khởi động sẽ được phát lại, do đó lần truy cập thứ hai sẽ có chi phí rẻ.

Bạn không cần điều chỉnh số lần thử lại, kích thước pool, hoặc số lượng proxy. FourA tự học các thông số này cho từng host.

Request Body

Tham số Kiểu dữ liệu Bắt buộc Mặc định Mô tả
url string Có - URL mục tiêu
method string Không "GET" Phương thức HTTP
headers [string, string][] Không - Các header tùy chỉnh dưới dạng cặp [tên, giá trị]
data any Không - Request body cho các request không phải là GET
validate object Không - Tiêu chí thành công, có cấu trúc giống như validate của Single Request (xem bên dưới). Cho hệ thống auto biết một trang thực sự trông như thế nào để nó có thể phân biệt nội dung thật với trang thử thách.
returnSession boolean Không true Bao gồm session chiến thắng (proxy, cookies, userAgent) trong response để bạn có thể phát lại thông qua /api/single/ hoặc /api/browser/.
forceProxy boolean Không true Luôn định tuyến qua một proxy xoay vòng. Đặt thành false để cho phép đường dẫn trực tiếp rẻ hơn khi mục tiêu cho phép (một số hệ thống phòng thủ nghiêm ngặt hơn đối với lưu lượng proxy).
timeout_ms integer Không 120000 Tổng ngân sách thời gian cho toàn bộ cuộc gọi, tính bằng mili giây. Tất cả các lần thử nghiệm phụ đều chạy trong giới hạn này. Tối thiểu 5000, tối đa 180000.
ignoreProxies string[] Không - ID proxy cần tránh trong mọi lần thử phụ. Sử dụng các ID được trả về từ các response /api/auto/ hoặc /api/proxy/ trước đó.
followRedirects integer Không 5 Số lần chuyển hướng tối đa để theo dõi trên các bước rẻ tiền. 0 để tắt. Tối đa 20.

Response

{
  "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..."
  }
}
Trường Loại Mô tả
status number Trạng thái HTTP từ mục tiêu.
data string or object Nội dung response.
headers array or object Các header response của mục tiêu. Các rung single và proxy trả về một mảng chứa các đối tượng header trên mỗi hop, các rung browser trả về một đối tượng phẳng.
meta.rung string Rung (bậc) ladder nào đã cung cấp response. Một trong số: probe (request trực tiếp giá rẻ), proxy (proxy xoay vòng), browser (render trình duyệt đầy đủ), cache (phát lại phiên khởi động trước), hoặc fail (không có rung nào tạo ra response được chấp nhận).
meta.solved boolean Liệu một bot challenge có được giải quyết trong lần gọi này hay không.
meta.attempts number Số lần thử phụ đã thực hiện trước khi thành công.
meta.credits number Tổng credit đã tiêu tốn cho lần gọi này. Khớp với X-FourA-Credits.
session.proxy string ID được mã hóa của proxy đã cung cấp response. Tái sử dụng nó trong một request Single hoặc Browser. Xuất hiện khi returnSession là true.
session.cookies array Các cookie từ lần thử thành công. Xuất hiện khi returnSession là true.
session.userAgent string User-Agent được sử dụng trong lần thử thành công. Xuất hiện khi returnSession là true.
error string Thông báo lỗi nếu cuộc gọi thất bại.

Ví dụ

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

Lưu ý

  • Auto là một bộ điều phối. Nó gọi Single, Proxy hoặc Browser ở bên trong và chuyển tiếp API key của bạn đến từng lệnh gọi phụ (sub-call). Mỗi sub-call sẽ xuất hiện trong Nhật ký hoạt động của bạn, lệnh gọi /api/auto/ bên ngoài không cộng thêm một hàng tính phí riêng biệt.
  • Truyền validate.data.accept với một chuỗi con mà chỉ trang thực mới có. Nếu không có nó, auto không thể phân biệt được mã 200 thực sự và một trang trung gian challenge được trả về với trạng thái 200.
  • timeout_ms giới hạn toàn bộ lệnh gọi. Một lệnh gọi đầu tiên (cold) đến một trang web được bảo vệ có thể mất hàng chục giây, các session được dùng lại (warm) thường hoàn thành trong vòng chưa tới một giây.

Single Request

POST /api/single/

Gửi một request HTTP với các đặc tính mạng giống hệt như trình duyệt thực tế mà không cần khởi chạy một trình duyệt thực. Đây là endpoint nhanh nhất.

Request Body

Tham số Loại Bắt buộc Mặc định Mô tả
method string Có - Phương thức HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Có - URL đích. Sử dụng {ts} ở bất kỳ đâu trong URL để chèn timestamp hiện tại cho việc cache-busting.
headers [string, string][] Không - Các header tùy chỉnh dưới dạng các cặp [name, value]
unblocker boolean Không true Gửi các browser header thực tế (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Mặc định được bật. Đặt false để gửi một chữ ký client thuần túy.
timeout_ms number Không 15000 Tổng thời gian timeout tính bằng ms (tối đa: 120000)
connect_timeout_ms number Không 5000 Thời gian connection timeout tính bằng ms
accept_timeout_ms number Không 5000 Thời gian accept timeout tính bằng ms (thời gian chờ chấp nhận kết nối)
server_response_timeout_ms number Không 15000 Thời gian server response timeout tính bằng ms (thời gian chờ byte đầu tiên)
dns_cache_timeout_sec number Không 120 Thời gian TTL của DNS cache tính bằng giây (tối đa: 240)
followRedirects number Không disabled Số lượng redirect tối đa để theo dõi (0-20). Bỏ qua để vô hiệu hóa.
tryJsonData boolean Không false Phân tích cú pháp body của response thành JSON nếu có thể
returnBuffer boolean Không false Trả về buffer thô thay vì chuỗi đã được giải mã
data any Không - Body của request (chuỗi hoặc đối tượng, được tự động tuần tự hóa thành JSON)
proxy string Không - Proxy ID từ một response trước đó, để ghim cùng một điểm thoát. Truyền lại chuỗi opaque nguyên bản. Một địa chỉ proxy thô sẽ bị từ chối với 400 Invalid proxy format.
browser string Không Chrome Trình duyệt để hiển thị: Chrome, Edge, Safari, Firefox, hoặc Tor. Xem Hồ sơ trình duyệt.
os string Không - Hệ điều hành để hiển thị: Windows, macOS, Android, hoặc iOS. Một tên dòng hệ điều hành sẽ chấp nhận bất kỳ phiên bản nào của nó.
version string Không newest Phiên bản trình duyệt để hiển thị, như được liệt kê trong danh mục. Phiên bản mới nhất phù hợp sẽ được chọn khi có nhiều phiên bản thỏa mãn.
profile string Không - ID hồ sơ chính xác từ GET /api/profiles, thay cho ba trường ở trên.
validate object Không - Các quy tắc xác thực response (xem bên dưới)

Hồ sơ trình duyệt

Theo mặc định, một request sẽ hiển thị Google Chrome mới nhất. Một số đích đến chấp nhận một trình duyệt và từ chối trình duyệt khác, do đó browser, os, và version thu hẹp một danh mục các hồ sơ đã được đo lường, và profile chọn một hồ sơ bằng id.

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

Quy tắc:

  • Việc lựa chọn yêu cầu unblocker (bật theo mặc định). Khi tắt unblocker, không có browser header nào được gửi đi, vì vậy request sẽ bị từ chối thay vì chỉ được áp dụng một nửa.
  • Khi có nhiều profile khớp, phiên bản mới nhất sẽ được ưu tiên.
  • Một tổ hợp mà catalogue không thể cung cấp sẽ trả về lỗi nêu rõ những gì có sẵn. Request không bao giờ được gửi dưới dạng một trình duyệt khác.
  • Bốn trường tương tự cũng có sẵn bên trong đối tượng request của POST /proxy/.

GET /api/profiles trả về toàn bộ catalogue và không cần API key:

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

osFamily là giá trị để lọc khi xây dựng bộ chọn; os giữ tên bản phát hành để hiển thị.

Quy tắc xác thực

Đối tượng validate cho phép bạn xác định các điều kiện thành công và thất bại. Nếu một điều kiện fail khớp, request sẽ được coi là thất bại. Nếu các điều kiện accept được thiết lập, chỉ các response khớp mới được coi là thành công.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Trường Loại Mô tả
validate.status.accept number[] Các mã trạng thái HTTP được chấp nhận
validate.status.fail number[] Các mã trạng thái HTTP bị từ chối
validate.headers.accept object Các cặp key-value của header phải tồn tại
validate.headers.fail object Các cặp key-value của header kích hoạt lỗi
validate.data.accept string[] Các chuỗi phải xuất hiện trong response body
validate.data.fail string[] Các chuỗi trong response body kích hoạt lỗi

Ví dụ

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

Phản hồi:

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

Khi target thực hiện bot check trong quá trình tải body, response cũng mang theo một object defense chỉ định vendor và cho biết kiểm tra có được vượt qua hay không:

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
Trường Kiểu Mô tả
status number Mã trạng thái HTTP từ đích
headers array Một đối tượng cho mỗi bước nhảy chuyển hướng. Mỗi đối tượng có một trường result với dòng trạng thái cộng với mọi header phản hồi. Các header nhiều giá trị (Set-Cookie, Link, WWW-Authenticate) trả về dưới dạng mảng các chuỗi.
data string/object Thân phản hồi (JSON nếu tryJsonData là true)
total_time number Tổng thời gian request tính bằng giây
proxy string ID được mã hóa của proxy mà request đã đi qua (chỉ khi proxy được cung cấp trên request). Sử dụng lại nó trong lệnh gọi tiếp theo để ghim cùng một điểm thoát.
defense object Chỉ xuất hiện khi đích chạy kiểm tra bot trên request này. defense.solved cho biết kiểm tra đã bị xóa hay chưa. Xem Anti-Bot Defenses để biết mọi trường và danh sách đầy đủ nhà cung cấp.
error string Thông báo lỗi nếu request thất bại

Proxy Request

POST /api/proxy/

Định tuyến request của bạn thông qua các proxy luân phiên với tự động thử lại khi thất bại. Tùy chọn phạm vi lựa chọn theo một tập hợp các quốc gia thoát có thể nhìn thấy được với đích.

Request Body

Tham số Kiểu Bắt buộc Mặc định Mô tả
request object Có - Một phần thân request (các trường tương tự như Single Request ở trên)
timeout_ms number Không 45000 Thời gian chờ tổng thể cho tất cả các lần thử tính bằng ms (tối đa: 120000)
maxTries number Không 5 Số lần thử luân phiên proxy tối đa (tối đa: 90)
ignoreProxies string[] Không - ID proxy cần loại trừ khỏi luân phiên (sử dụng các ID do các phản hồi trước đó trả về)
exitCountries string[] Không - Danh sách cho phép nghiêm ngặt các mã quốc gia có thể nhìn thấy với đích gồm hai chữ cái (ví dụ: ["CZ", "GB"]). Các giá trị được cắt bớt, viết hoa và loại bỏ trùng lặp. Các proxy với điểm thoát không xác định bị loại trừ và request không bao giờ lùi về quốc gia không được yêu cầu.

exitCountries scoping

Lựa chọn sử dụng siêu dữ liệu quốc gia có thể nhìn thấy với đích mới nhất hiện có, thường được làm mới trong vòng khoảng mười phút. Nó không phải là tra cứu vị trí địa lý trực tiếp trong quá trình request. Đừng suy luận quốc gia phục vụ từ địa chỉ máy chủ proxy.

Nếu nhóm hiện tại không có kết quả phù hợp với các quốc gia được yêu cầu, phản hồi sẽ trả về HTTP 200 kèm theo vỏ bọc lỗi:

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

Hãy giữ nguyên phạm vi đã yêu cầu và thử lại sau. Chỉ thay đổi hoặc mở rộng nó khi yêu cầu về quốc gia của luồng công việc của bạn thay đổi rõ ràng.

Ví dụ

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
}
Trường Loại Mô tả
proxy chuỗi Định danh đã mã hóa của proxy được sử dụng. Sử dụng lại nó trong request Single hoặc Browser bằng cách truyền nó qua trường proxy, hoặc bỏ qua nó trong request Proxy tiếp theo thông qua ignoreProxies.
exitCountry chuỗi Mã quốc gia hai chữ cái hiển thị với đích của proxy đã phục vụ request. Chỉ có mặt khi request thiết lập exitCountries. Luôn xác minh rằng đó là một trong các mã bạn đã yêu cầu trước khi tin tưởng response.
total số Tổng thời gian thực tính bằng giây (float). Bao gồm chọn proxy, số lần thử lại và lần thử thành công. total_time chỉ là request bên trong; total luôn >= total_time.
error chuỗi Thông báo lỗi nếu request thất bại. Trong trường hợp không tìm thấy phạm vi (scope miss), code là no_eligible_proxy và details.exitCountries lặp lại phạm vi đã chuẩn hóa.

Tất cả các trường response của Single Request cũng được bao gồm, trong đó có defense: một nỗ lực sử dụng proxy gặp bot check sẽ báo cáo điều đó theo cách giống như Single Request.

Browser Request

POST /api/browser/

Mở URL của bạn trong một phiên bản trình duyệt Chrome. Trang được tải, JavaScript thực thi, và bạn nhận được HTML được hiển thị đầy đủ cộng với cookie jar.

Request Body

Tham số Loại Bắt buộc Mặc định Mô tả
url chuỗi Có - URL đích
headers đối tượng Không - Các header tùy chỉnh dưới dạng cặp key-value
cookies mảng Không - Cookie cần thiết lập: [{name, value, domain?}]
userAgent chuỗi Không - Chuỗi User-Agent tùy chỉnh
unblocker boolean Không true Tự động giải quyết các thử thách bot thông thường (Cloudflare clearance, các cổng tương tự) trong khi tải trang. Bật theo mặc định. Đặt false để hiển thị bất kỳ nội dung nào trang trả về, bao gồm cả trang thử thách, mà không cần giải quyết.
proxy chuỗi Không - Proxy ID từ một response trước đó, để ghim cùng một điểm thoát. Truyền lại chuỗi không rõ ràng y nguyên. Một địa chỉ proxy thô sẽ bị từ chối bằng 400 Invalid proxy format.
timeout_ms số Không 30000 Thời gian chờ tải trang tính bằng ms (tối đa: 120000)
checkStatus số Không - Trạng thái HTTP mong đợi (request sẽ thất bại nếu khác)
checkText chuỗi Không - Văn bản phải xuất hiện trong trang được hiển thị

Ví dụ

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

Phản hồi:

{
  "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"
}
Trường Loại Mô tả
status number Mã trạng thái HTTP từ đích
headers object Header của phản hồi
body string hoặc object Nội dung trang đã được render hoàn chỉnh. Chuỗi HTML khi content-type là HTML; object khi trang trả về JSON và được tự động parse.
cookies array Các object cookie đầy đủ từ trang. Mỗi cookie bao gồm name, value, domain, path, expires, httpOnly, secure, sameSite, và các thuộc tính cookie khác.
userAgent string User-Agent của trình duyệt được sử dụng
defenseSolved boolean true nếu gặp hệ thống phòng chống bot và đã thực sự vượt qua trong lệnh gọi này. Không có mặt nếu ngược lại. Yếu tố này quyết định mức phí 15 hay 30 credit.
defenses object present liệt kê mọi vendor được nhận diện trong quá trình tải trang, cleared liệt kê các vendor mà trang cuối cùng đã vượt qua. Một vendor có thể xuất hiện trong present và không bao giờ xuất hiện trong cleared. Xem Hệ thống phòng chống Bot.
proxy string ID đã mã hóa của proxy mà request đi qua (chỉ khi một proxy được cung cấp trên request). Sử dụng lại nó trong các lệnh gọi tiếp theo để giữ nguyên đường ra.
error string Thông báo lỗi nếu request thất bại

Mã trạng thái HTTP

Mã Ý nghĩa
200 Request hoàn tất (kiểm tra status bên trong để xem phản hồi đích)
400 Body của request, tham số không hợp lệ, hoặc IP đích nằm trong dải private/dành riêng
401 Thiếu API key hoặc API key không hợp lệ
429 Vượt quá giới hạn rate limit
500 Lỗi máy chủ nội bộ
502 Upstream unavailable. FourA đã kết nối tới engine của nó nhưng phản hồi không thể sử dụng được. Thử lại.
503 Dịch vụ tạm thời bị vô hiệu hóa hoặc quá tải, hoặc Backend service unavailable trong khi engine đang khởi động lại
504 Upstream timeout. Engine không hoàn thành trong khoảng thời gian cho phép của request này. Tăng timeout_ms hoặc thử lại.

Các bước tiếp theo

Cập nhật: 12 tháng 8, 2026
Lỗi API →