Tham chiếu API Endpoints

Tài liệu tham khảo cho tất cả các API endpoint của FourA kèm theo 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ý API key trong Dashboard. Các key sử dụng tiền tố pk_live_.

Response Headers

Response từ /api/* chứa hai correlation header:

Header	Value	Description
`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, ngoại trừ body mà FourA hoàn toàn không thể đọc: `400 Invalid JSON in request body` và `413` bị từ chối trước khi ID được gán. Hãy ghi log giá trị này ở phía bạn.
`X-FourA-Credits`	integer	Số credit đã dùng cho request này. Được trả về trên mọi response đã đến được engine, dù thành công hay thất bại (vì tác vụ đều đã được thực thi). Lượt gọi bị FourA từ chối trước khi bất kỳ engine nào chạy (key bị thiếu hoặc không hợp lệ, giới hạn gói hoặc nền tảng, target hoặc proxy ID bị từ chối) sẽ không có header này. Xem Request Outcomes để biết kết quả nào bị tính phí.

Cùng một request ID đó sẽ định danh bản xem trước payload của request và response trong Activity Log trên Dashboard (được lưu 24 giờ, 200 lượt gần nhất cho mỗi key), giúp bạn có thể tra cứu lại chính xác request sau đó và phát lại trực tiếp từ Activity vào Playground. Hãy đính kèm ID này khi liên hệ bộ phận hỗ trợ để 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? Server @fouradata/mcp đóng gói 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 cấu trúc đầu vào kèm tùy chọn offload_large để xử lý response lớn tối ưu token.

FourA cung cấp bốn endpoint request, mỗi endpoint được tối ưu hóa cho một trường hợp sử dụng khác nhau:

Endpoint	Phù hợp nhất cho
`POST /auto/`	Smart fetch. Bạn truyền URL, FourA sẽ chọn phương thức tiết kiệm chi phí nhất có thể hoạt động (trực tiếp, proxy luân phiên, hoặc trình duyệt) và ghi nhớ phương thức hoạt động cho từng host.
`POST /single/`	HTTP request nhanh, trang tĩnh, API
`POST /proxy/`	Các trang web được bảo vệ với tính năng luân phiên proxy tự động, tùy chọn phạm vi 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.

Để tìm hiểu chi tiết hơn về thời điểm nên chọn từng loại, hãy xem Choosing the Right Endpoint và hướng dẫn Smart Fetch.

Target URL Restrictions

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

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

Smart Fetch (Auto)

POST /api/auto/

Bạn truyền vào một URL cùng các quy tắc validate tùy chọn. FourA duyệt qua một thang tối ưu chi phí (thăm dò trực tiếp chi phí thấp, rotated proxy, trình duyệt đầy đủ) và dừng lại ở bậc thang đầu tiên trả về response được các quy tắc của bạn chấp nhận. Đối với các lệnh gọi lặp lại đến cùng một host, một warm session sẽ được phát lại thay thế, giúp lượt truy cập thứ hai tiết kiệm chi phí.

Bạn không cần tinh chỉnh số lần thử lại, kích thước pool, hoặc số lượng proxy. FourA tự học chúng theo từng host.

Request Body

Tham số	Loại	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	-	Header tùy chỉnh dưới dạng các cặp [name, value]
`data`	any	Không	-	Request body cho các request không phải GET
`validate`	object	Không	-	Tiêu chí thành công, cùng cấu trúc với `validate` của Single Request (xem bên dưới). Khai báo cho auto biết cấu trúc của một trang hợp lệ để phân biệt nội dung thực tế với trang thử thách (challenge page).
`returnSession`	boolean	Không	`true`	Bao gồm session thành công (`proxy`, `cookies`, `userAgent`) trong response để bạn có thể phát lại qua `/api/single/` hoặc `/api/browser/`.
`forceProxy`	boolean	Không	`true`	Luôn định tuyến qua rotating proxy. Đặt `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ủ kiểm soát chặt chẽ hơn đối với lưu lượng proxy).
`timeout_ms`	integer	Không	`120000`	Tổng thời gian giới hạn cho toàn bộ lệnh gọi, tính bằng mili giây. Tất cả nỗ lực phụ đều chạy trong giới hạn thời gian này. Tối thiểu `5000`, tối đa `180000`.
`ignoreProxies`	string[]	Không	-	Danh sách Proxy ID cần tránh trong mỗi nỗ lực phụ. Sử dụng 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 cần theo dõi trên các bậc thang chi phí thấp. `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	Mã trạng thái HTTP từ máy chủ đích.
`data`	string	Body của response dưới dạng văn bản, từ bất kỳ bậc nào đã phục vụ response. Trang JSON trả về dạng văn bản JSON, vì vậy bạn cần tự phân tích cú pháp.
`headers`	array hoặc object	Các header của response từ máy chủ đích. Bậc single và proxy trả về một mảng chứa các đối tượng header theo từng chặng; bậc browser trả về một đối tượng phẳng.
`meta.rung`	string	Bậc nào trong thang đã phân phối response. Một trong các giá trị: `probe` (request trực tiếp giá rẻ), `proxy` (rotating proxy), `browser` (render toàn bộ trình duyệt), `cache` (phiên làm việc ấm được phát lại), `warmup` (trang lối vào của trang web được tải trước và cookie của nó đã mở URL sâu), hoặc `fail` (không có bậc nào tạo ra response được chấp nhận).
`meta.solved`	boolean	Trang có cần thêm một bước phụ (trang thử thách) và nó đã được hoàn thành trong lệnh 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 số credit đã dùng cho lệnh gọi này. Khớp với `X-FourA-Credits`.
`session.proxy`	string	ID mã hóa của proxy đã phân phối response. Có thể tái sử dụng nó trên request Single hoặc Browser. Xuất hiện khi `returnSession` là `true`.
`session.cookies`	array	Cookie từ lần thử thành công. Xuất hiện khi `returnSession` là `true`.
`session.userAgent`	string	User-Agent đã dùng ở 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 lệnh 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"]}}
  }'

Ghi chú

Auto đóng vai trò điều phối. Nó gọi Single, Proxy hoặc Browser nội bộ và chuyển tiếp API key của bạn tới từng lệnh gọi con. Lệnh gọi Auto được tính là một request trong Activity Log và trên Overview của bạn, với tổng số credit từ các lệnh gọi con; các lệnh gọi con được liệt kê bên dưới dưới dạng các lần thử (attempts), và chúng không bao giờ được tính là các request 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 mã 200 thực sự với trang chuyển tiếp thử thách (challenge interstitial) trả về mã 200.
timeout_ms giới hạn thời gian cho toàn bộ lệnh gọi. Lần truy cập cold hit đầu tiên đến một trang web được bảo vệ có thể mất hàng chục giây; các warm session được tái sử dụng thường hoàn thành dưới một giây.

Single Request

POST /api/single/

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

Request Body

Tham số	Loại	Bắt buộc	Mặc định	Mô tả
`method`	string	Có	-	HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
`url`	string	Có	-	URL đích. Dùng `{ts}` ở bất kỳ đâu trong URL để chèn timestamp hiện tại nhằm bỏ qua cache.
`headers`	[string, string][]	Không	-	Header tùy chỉnh dưới dạng các cặp [tên, giá trị]
`unblocker`	boolean	Không	`true`	Gửi header trình duyệt thực tế (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Bật theo mặc định. Đặt `false` để gửi chữ ký client thuần túy.
`timeout_ms`	number	Không	15000	Timeout tổng thể tính bằng ms (tối đa: 120000)
`connect_timeout_ms`	number	Không	5000	Timeout kết nối tính bằng ms
`accept_timeout_ms`	number	Không	5000	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	Timeout phản hồi máy chủ tính bằng ms (thời gian chờ byte đầu tiên)
`dns_cache_timeout_sec`	number	Không	120	TTL bộ nhớ đệm DNS tính bằng giây (tối đa: 240)
`followRedirects`	number	Không	disabled	Số lần chuyển hướng tối đa cần theo (0-20). Bỏ qua để tắt.
`tryJsonData`	boolean	Không	false	Phân tích cú pháp body phản hồi thành JSON nếu có thể
`returnBuffer`	boolean	Không	false	Trả về buffer thô thay vì chuỗi đã giải mã
`data`	any	Không	-	Request body (chuỗi hoặc đối tượng, tự động tuần tự hóa thành JSON)
`proxy`	string	Không	-	Proxy ID từ phản hồi trước đó, dùng để ghim cùng một exit. Truyền lại chính xác chuỗi mờ này. Địa chỉ proxy thô sẽ bị từ chối với `400 Invalid proxy format`. Một số ID không thể ghim: xem Ghim một exit.
`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. 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. Kết quả phù hợp mới nhất 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 vì ba trường ở trên.
`validate`	object	Không	-	Quy tắc xác thực phản hồi (xem bên dưới)

Hồ sơ trình duyệt

Theo mặc định, request sẽ hiển thị là Google Chrome mới nhất. Một số mục tiêu chấp nhận trình duyệt này và từ chối trình duyệt khác, vì vậy browser, os và version sẽ thu hẹp danh mục các hồ sơ đã đo lường, và profile chọn một hồ sơ theo 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 unblocker tắt, không có header trình duyệt nào được gửi, do đó request sẽ bị từ chối thay vì áp dụng một nửa.
Khi nhiều profile khớp, phiên bản mới nhất sẽ được chọn.
Một tổ hợp mà danh mục không thể cung cấp sẽ trả về lỗi nêu rõ những mục hiện có. 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 khả dụng bên trong đối tượng request của POST /proxy/.

GET /api/profiles trả về toàn bộ danh mục 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 picker; 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 xử lý 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 xử lý 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	Kiểu	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 bắt buộc phải có
`validate.headers.fail`	object	Các cặp key-value của header gây ra lỗi
`validate.data.accept`	string[]	Các chuỗi bắt buộc phải xuất hiện trong response body
`validate.data.fail`	string[]	Các chuỗi trong response body gây ra 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
  }'

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

Khi mục tiêu chạy bước kiểm tra bot trước khi trả về body, response cũng sẽ mang theo một object defense nêu rõ nhà cung cấp và liệu kiểm tra đó đã được vượt qua hay chưa:

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}

Field	Type	Description
`status`	number	Mã trạng thái HTTP từ target
`headers`	array	Một đối tượng cho mỗi bước chuyển hướng (redirect hop). Mỗi đối tượng có trường `result` chứa dòng trạng thái và mọi header phản hồi. Các header có nhiều giá trị (`Set-Cookie`, `Link`, `WWW-Authenticate`) được trả về dưới dạng mảng chuỗi.
`data`	string/object	Nội dung phản hồi (JSON nếu `tryJsonData` là true)
`total_time`	number	Tổng thời gian thực hiện request tính bằng giây
`proxy`	string	ID đã mã hóa của proxy mà request đi qua (chỉ xuất hiện khi `proxy` được cung cấp trong request). Tái sử dụng ID này trong lần gọi tiếp theo để cố định cùng một exit node.
`defense`	object	Xuất hiện khi target chạy kiểm tra bot trên request này, hoặc khi việc thử lại với cookie của chính trang web lấy được nội dung. `defense.solved` cho biết việc kiểm tra đã được vượt qua hay chưa, `defense.retry` cho biết việc thử lại có lấy được nội dung hay không. Xem Site checks để biết toàn bộ các trường và danh sách hệ thống đầy đủ.
`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 qua các proxy xoay vòng với cơ chế tự động thử lại khi thất bại. Tùy chọn giới hạn phạm vi lựa chọn theo danh sách các quốc gia exit hiển thị với target.

Request Body

Parameter	Type	Required	Default	Description
`request`	object	Yes	-	Request body đơn lẻ (cùng các trường như Single Request ở trên)
`timeout_ms`	number	No	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	No	5	Số lần thử xoay vòng proxy tối đa (tối đa: 90)
`ignoreProxies`	string[]	No	-	Danh sách Proxy ID cần loại trừ khỏi vòng xoay (sử dụng ID được trả về từ các phản hồi trước đó)
`exitCountries`	string[]	No	-	Danh sách cho phép nghiêm ngặt gồm mã quốc gia hai chữ cái hiển thị với target (ví dụ: `["CZ", "GB"]`). Các giá trị được cắt khoảng trắng, chuyển thành chữ hoa và loại bỏ trùng lặp. Proxy có exit không xác định sẽ bị loại trừ và request không bao giờ dự phòng về một quốc gia không được yêu cầu.
`exitClass`	string	No	-	`standard` hoặc `premium`. `premium` cho phép request nâng cấp lên exit cao cấp (premium) khi pool tiêu chuẩn gặp khó khăn trên target có bảo vệ. Yêu cầu gói dịch vụ có bao gồm premium exit.

Phạm vi exitCountries

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

Nếu pool hiện tại không có kết quả khớ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 cấu trúc lỗi (error envelope):

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

Giữ nguyên scope đã yêu cầu và thử lại sau. Chỉ thay đổi hoặc mở rộng scope khi yêu cầu quốc gia của quy trình làm việc 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	Kiểu	Mô tả
`proxy`	string	Định danh đã mã hóa của proxy được sử dụng. Tái sử dụng nó trên một Single request hoặc Browser request bằng cách truyền nó vào trường `proxy`, hoặc bỏ qua nó trên Proxy request tiếp theo qua `ignoreProxies`.
`exitCountry`	string	Mã quốc gia hai chữ cái mà phía đích nhìn thấy của proxy đã phục vụ request. Chỉ xuất hiện khi request có thiết lập `exitCountries`. Luôn xác minh đây là một trong các mã bạn đã yêu cầu trước khi tin cậy response.
`exitClass`	string	Hạng exit node nào đã phục vụ request này, xuất hiện trên response thành công khi request có chỉ định. `premium` nghĩa là một exit node premium đã trả về body; `standard` nghĩa là pool tiêu chuẩn đã thực hiện. Một lệnh gọi thất bại không phục vụ nội dung nào, do đó nó không có `exitClass`; hãy đọc `attemptReport` của nó để biết các lần thử đã gặp sự cố gì.
`total`	number	Tổng thời gian thực tế bên ngoài tính bằng giây (số thực). Bao gồm việc chọn proxy, các lần thử lại và lần thử thành công. `total_time` chỉ tính riêng request bên trong; `total` luôn >= `total_time`.
`profile`	string	Profile trình duyệt mà cơ chế xoay vòng đã chọn, chỉ xuất hiện khi nó khác với profile bạn đã yêu cầu. Vắng mặt nghĩa là request được gửi đi chính xác như mô tả ban đầu. Truyền id này lại dưới dạng `profile` trong các lệnh gọi tiếp theo để giữ lại trình duyệt đã hoạt động tốt.
`error`	string	Thông báo lỗi nếu request thất bại. Khi không khớp scope, `code` sẽ là `no_eligible_proxy` và `details.exitCountries` sẽ phản hồi lại scope đã được chuẩn hóa.
`attemptReport`	object	Xuất hiện trên mọi lệnh gọi Proxy thất bại. Đếm số lượng sự cố các lần thử đã gặp phải, giúp phân biệt giữa pool bị chặn, pool không hoạt động và quy tắc `validate` không khớp thay vì hiển thị cùng một lỗi. Xem bên dưới.

Tất cả các trường response của Single Request cũng được bao gồm, trong đó có defense: một lần thử proxy gặp kiểm tra bot sẽ báo cáo tương tự như Single.

Lý do một Proxy Call thất bại

Download maxTry limit reached hiển thị giống nhau bất kể các lần thử diễn ra theo hướng nào, vì vậy mỗi Proxy response thất bại đều mang theo một attemptReport bên cạnh lỗi:

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

Trường	Kiểu	Mô tả
`total`	integer	Số lần thử đã thực hiện
`noResponse`	integer	Điểm thoát không phản hồi, do đó chưa bao giờ tiếp cận được trang web
`defense`	integer	Trang web đã phản hồi và phát hiện kiểm tra bot trên phản hồi đó
`contentRejected`	integer	HTTP 200, không có kiểm tra bot, chỉ bị từ chối bởi `validate.data` của bạn
`statusRejected`	integer	Trang web đã phản hồi, không có kiểm tra bot, bị từ chối bởi `validate.status` của bạn
`other`	integer	Đã phản hồi, và không thuộc các trường hợp trên
`vendors`	string[]	Các nhà cung cấp kiểm tra bot được nhận diện trong tác vụ
`profilesTried`	string[]	Các hồ sơ trình duyệt mà tác vụ đã gửi, theo thứ tự sử dụng đầu tiên. `default` có nghĩa là request của bạn được gửi đi nguyên vẹn.
`summary`	string	Một câu được tạo từ các số lượng đếm, an toàn để ghi log

Chuỗi error không thay đổi, vì vậy client khớp theo chuỗi này vẫn tiếp tục hoạt động. Hướng xử lý cho từng số lượng đếm: Tại sao một Proxy Request hết số lần thử.

exitClass

Một số mục tiêu từ chối các điểm thoát trong pool tiêu chuẩn cho dù thử bao nhiêu lần. exitClass: premium thông báo cho Proxy rằng nó có thể chuyển tiếp request đó sang một premium exit ngoài pool tiêu chuẩn, thay vì chỉ xoay vòng bên trong pool đó.

{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}

Có ba điều cần lưu ý trước khi bạn gửi nó.

Đây là mức cho phép, không phải chỉ thị bắt buộc. Standard pool vẫn đồng thời xử lý để phản hồi, và thường sẽ thành công trước. Premium exit chỉ tham gia khi pool đã dùng hết một khoảng thời gian giới hạn ngắn cho request hoặc mục tiêu từ chối rõ ràng. Request mà standard pool phản hồi trước khi bất kỳ premium exit nào được thử nghiệm sẽ tính là thành công bình thường và không tốn lưu lượng premium. Khi một premium exit đã được thử nghiệm, lưu lượng của nó sẽ được tính như mô tả bên dưới.

Response sẽ cho biết thành phần nào thực sự phục vụ bạn. Khi bạn chỉ định một class, response sẽ trả về exitClass:

{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}

premium nghĩa là một exit cao cấp đã trả về body. standard nghĩa là standard pool đã xử lý, đây cũng là kết quả bạn nhận được khi không thể lấy được exit cao cấp, và khi lưu lượng premium đi kèm trong gói của bạn (cùng với phần mua thêm) đã dùng hết trong chu kỳ thanh toán. Cả hai đều không phải là lỗi, và bạn có thể đối soát lưu lượng premium của mình dựa trên các giá trị này theo từng request thay vì dựa vào số liệu hàng tháng. Cùng một giá trị được truyền trong response header X-FourA-Exit-Class (xem Response Headers).

Lưu lượng premium được đo lường trên mạng. Một lượt thử premium tính lượng dữ liệu đã gửi và nhận khi đi qua mạng, đã được nén và mã hóa trong quá trình truyền, bất kể nó có trả về trang của bạn hay không. Lượt thử vẫn đang chạy khi một exit khác đã phản hồi sẽ bị dừng ngay lập tức và không bị tính. Lưu lượng premium được tính vào hạn mức premium và cũng nằm trong tổng băng thông của bạn: cùng một lượng byte, được báo cáo hai lần, không bao giờ cộng dồn lại với nhau. Khi một exit cao cấp phân phối trang, lưu lượng của nó chính là toàn bộ lưu lượng của request, vì vậy trang sẽ không bị tính thêm một lần nữa dưới dạng lưu lượng standard. Trang Usage & Limits của bạn hiển thị tổng lưu lượng, tỷ lệ premium trong đó, và hạn mức premium dùng để đối chiếu.

Bỏ qua trường này không giống với việc gửi standard. Bỏ qua trường này khiến quyết định chưa được xác định; gửi standard chỉ định rõ ràng rằng request này không bao giờ được phép escalate, đây là cách để giữ một job cụ thể hoàn toàn không dùng đến lưu lượng premium.

Hết hạn mức không phải là lỗi. Một request chỉ định premium sau khi hết hạn mức vẫn tiếp tục hoạt động: standard pool sẽ phục vụ request đó và response trả về standard. Không có job nào bị dừng lại do hết hạn mức.

exitClass: premium yêu cầu gói dịch vụ có bao gồm các exit cao cấp. Với gói không có các exit này, request sẽ không bao giờ tiêu tốn exit cao cấp: request sẽ bị từ chối với mã 403 kèm X-FourA-Limit: plan_limit_premium (xem Rate Limits), hoặc được phục vụ từ standard pool với exitClass: standard trong response. Hãy xử lý cả hai trường hợp.

Browser Profile Rotation

Proxy thực hiện xoay vòng các exit. Khi một trang web từ chối trình duyệt mà FourA cung cấp thay vì từ chối exit xuất phát, Proxy cũng sẽ chuyển sang một nhóm trình duyệt khác từ danh mục. Cơ chế này không thêm lượt thử nào: việc xoay vòng chỉ thay đổi nội dung gửi trong lần thử lại, không bao giờ thay đổi việc có thử lại hay không.

Proxy cũng ghi nhớ, trong một khoảng thời gian, nhóm trình duyệt mà trang web chấp nhận gần nhất, để lệnh gọi sau đó tới cùng một trang có thể bắt đầu bằng nhóm đó thay vì mặc định. Response sẽ nêu tên nhóm đó trong profile, tương tự như đối với bất kỳ nhóm nào mà cơ chế xoay vòng đã chọn.

Giá trị profile, browser, os, hoặc version được chỉ định rõ ràng trên request bên trong của bạn sẽ không bao giờ bị ghi đè, và request mang header User-Agent hoặc Cookie riêng cũng vậy, vì clearance được liên kết với chữ ký đã tạo ra nó.

Browser Request

POST /api/browser/

Mở URL của bạn trong một phiên trình duyệt Chrome. Trang sẽ tải, JavaScript được thực thi, và bạn nhận lại HTML đã render hoàn chỉnh cùng với cookie jar.

Request Body

Parameter	Type	Required	Default	Description
`url`	string	Có	-	URL mục tiêu
`headers`	object	Không	-	Header tùy chỉnh dưới dạng các cặp key-value
`cookies`	array	Không	-	Cookie cần thiết lập: `[{name, value, domain?}]`
`userAgent`	string	Không	-	Chuỗi User-Agent tùy chỉnh
`unblocker`	boolean	Không	`true`	Hoàn thành bước kiểm tra mà trang yêu cầu trước khi tải (trang challenge hoặc cổng chặn tương tự). Bật theo mặc định. Đặt `false` để render nguyên trạng nội dung trang trả về, bao gồm cả trang challenge.
`proxy`	string	Không	-	Proxy ID từ response trước đó, dùng để cố định cùng một điểm exit. Truyền lại chuỗi opaque nguyên văn. Địa chỉ proxy thô sẽ bị từ chối với `400 Invalid proxy format`.
`exitCountry`	string	Không	-	Mã quốc gia gồm hai chữ cái (ISO 3166-1 alpha-2) của quốc gia mà request đi ra. Thiết lập đồng hồ của trình duyệt theo múi giờ tương ứng. Xem Khớp đồng hồ trình duyệt với điểm exit.
`timeout_ms`	number	Không	30000	Thời gian chờ tải trang tính bằng ms (tối đa: 120000)
`checkStatus`	number	Không	-	HTTP status dự kiến (request sẽ thất bại nếu khác)
`checkText`	string	Không	-	Văn bản bắt buộc phải xuất hiện trong trang đã render

Khớp đồng hồ trình duyệt với điểm exit

Một trang có thể đọc múi giờ của trình duyệt và so sánh với quốc gia của IP mà nó thấy. Sự không khớp là một trong những tín hiệu đơn giản nhất mà hệ thống phát hiện bot sử dụng, và bạn hoàn toàn có thể loại bỏ nó mà không tốn chi phí nào.

Thiết lập exitCountry thành quốc gia mà lưu lượng của bạn đi ra và trình duyệt sẽ báo cáo múi giờ thuộc về quốc gia đó:

{
  "url": "https://example.com",
  "proxy": "A1B2C3",
  "exitCountry": "BR"
}

Quy tắc:

Giá trị này là quốc gia exit, nghĩa là quốc gia mà mục tiêu nhìn thấy, không phải nơi proxy được đặt host. Hai thông tin này thường xuyên khác nhau.
Nếu bỏ qua, FourA sẽ sử dụng quốc gia exit khi xác định được, hoặc giữ nguyên đồng hồ trình duyệt thay vì tự đoán.
Mã quốc gia mà FourA không nhận diện được sẽ được xử lý tương tự như khi bỏ trống trường này. Đây không phải là lỗi.
Chỉ có đồng hồ tuân theo quốc gia. Accept-Language và nội dung trang web cung cấp được giữ nguyên, vì vậy trang sẽ không tự động đổi ngôn ngữ.

Tham số `userAgent`

Gửi userAgent và chuỗi chính xác đó là những gì trang, worker của trang và mục tiêu nhìn thấy. FourA cũng tự suy ra client hint tương ứng từ chuỗi này (sec-ch-ua, sec-ch-ua-platform, navigator.platform, và các giá trị high-entropy mà hệ thống phát hiện yêu cầu theo tên), do đó request không bị tình trạng khai báo một trình duyệt trong header và một trình duyệt khác trong JavaScript.

userAgent trong response là chuỗi đã được hiển thị. Điều này rất quan trọng khi bạn phát lại clearance: cookie cf_clearance được liên kết với exit và User-Agent đã nhận được nó, vì vậy hãy gửi lại chuỗi mà response đã báo cáo, không phải chuỗi bạn nghĩ đã được dùng. Xem Site checks.

Nếu gửi một chuỗi non-Chromium (chẳng hạn như Firefox User-Agent), chuỗi đó sẽ được hiển thị nguyên trạng, không đính kèm danh sách thương hiệu Chromium.

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

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

Trường	Kiểu	Mô tả
`status`	number	HTTP status code từ target
`headers`	object	Response headers
`body`	string or object	Nội dung trang đã render hoàn chỉnh. Là string HTML khi content-type là HTML; là object khi trang trả về JSON và được tự động parse.
`cookies`	array	Toàn bộ cookie objects 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	Trình duyệt User-Agent đã dùng
`defenseSolved`	boolean	`true` nếu gặp cơ chế chống bot và đã vượt qua thành công trong lượt gọi này. Không xuất hiện trong các trường hợp khác. Quyết định lượt gọi tốn 5 hay 10 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 thành công. Một vendor có thể xuất hiện trong `present` mà không bao giờ có trong `cleared`. Xem Site checks.
`proxy`	string	ID đã mã hóa của proxy mà request đi qua (chỉ có khi `proxy` được cung cấp trong request). Sử dụng lại ID này cho các lượt gọi tiếp theo để giữ nguyên exit.
`error`	string	Thông báo lỗi nếu request thất bại

Ghim một Exit

Giá trị proxy trong Single hoặc Browser request sẽ ghim exit mà một lượt gọi trước đó đã sử dụng. Hãy truyền lại chính xác opaque ID nhận được, không dùng địa chỉ proxy.

Ba giá trị sau sẽ bị từ chối, tất cả đều trả về mã 400:

Lỗi	Ý nghĩa
`Invalid proxy format`	Giá trị không phải là ID do FourA phát hành. Địa chỉ proxy thô sẽ rơi vào trường hợp này.
`Proxy not found`	ID đã giải mã, nhưng không còn trỏ đến một exit đang hoạt động. Hãy lấy một ID mới từ lượt gọi mới.
`Managed exit: this proxy id cannot be pinned to a request`	Exit tồn tại, nhưng không phải là loại FourA duy trì mở cho một request cụ thể. ID của exit premium sẽ rơi vào trường hợp này khi gói của bạn không còn lưu lượng premium. Hãy dùng lại session đã trả về ID đó, hoặc chạy lượt gọi qua `POST /api/proxy/` và nhận bất kỳ exit nào được chọn.

Một exit premium được ghim sẽ được tính phí theo lưu lượng premium. Response chứa X-FourA-Exit-Class: premium để bạn theo dõi theo từng request, và lưu lượng mà exit đã truyền tải sẽ được tính vào lưu lượng premium trên trang Usage & Limits cũng như tổng băng thông của bạn, bất kể trang web có trả về nội dung bạn muốn hay không. Việc ghim yêu cầu gói của bạn phải có exit premium và còn hạn mức; nếu không ID sẽ bị từ chối với lỗi 400 managed-exit ở trên.

HTTP Status Codes

Mã	Ý nghĩa
200	Request đã hoàn thành (kiểm tra `status` bên trong để xem response từ mục tiêu)
400	Request body hoặc tham số không hợp lệ, IP mục tiêu thuộc dải riêng tư/dành riêng, hoặc ID proxy không thể ghim
401	API key bị thiếu hoặc không hợp lệ
403	Endpoint hoặc tham số không có trong gói của bạn. `X-FourA-Limit` chỉ rõ: `plan_limit_feature` hoặc `plan_limit_premium`.
404	`Not Found`: không có endpoint tại đường dẫn đó.
413	Request body JSON vượt quá 100 KB. Kết quả trả về không phải JSON và không chứa `X-FourA-Request-Id`.
429	Đạt giới hạn gói (`X-FourA-Limit` được thiết lập) hoặc hạn mức chia sẻ mỗi phút của nền tảng (không có header)
500	Lỗi máy chủ nội bộ
502	`Upstream unavailable`. FourA đã kết nối tới engine nhưng phản hồi không thể sử dụng. Hãy 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 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. Hãy tăng `timeout_ms` hoặc thử lại.

Các bước tiếp theo

Smart Fetch (Auto): Khi nào nên để FourA tự chọn đường dẫn cho bạn
Chọn đúng Endpoint: Khi nào nên tự chọn Single, Proxy hoặc Browser
Xác thực: Quản lý API key của bạn
Xử lý lỗi: Xử lý lỗi một cách linh hoạt
Kiểm tra trang web: Đọc trường defense và phát lại clearance
Lý do Proxy Request hết số lần thử: Đọc attemptReport và xử lý theo đó
Rate Limit: Tìm hiểu về các giới hạn request
Bắt đầu nhanh: Thực hiện request đầu tiên của bạn trong 30 giây

Cập nhật: 30 tháng 9, 2026

Tham chiếu API Endpoints

Base URL

Xác thực

Response Headers

Endpoints

Target URL Restrictions

Smart Fetch (Auto)

Request Body

Response

Ví dụ

Ghi chú

Single Request

Request Body

Hồ sơ trình duyệt

Quy tắc xác thực

Ví dụ

Proxy Request

Request Body

Phạm vi exitCountries

Ví dụ

Lý do một Proxy Call thất bại

exitClass

Browser Profile Rotation

Browser Request

Request Body

Khớp đồng hồ trình duyệt với điểm exit

Tham số userAgent

Ví dụ

Ghim một Exit

HTTP Status Codes

Các bước tiếp theo

Tham số `userAgent`