Справочник API endpoints
Справочник по всем endpoints API FourA с параметрами request и форматами response.
Базовый URL
https://eu.api.foura.ai/api
Аутентификация
Для каждого запроса требуется ваш API key в 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"}'
Создавайте API keys и управляйте ими в Dashboard. Ключи используют префикс pk_live_.
Заголовки ответа
Ответы от /api/* содержат два correlation headers:
| Header | Value | Description |
|---|---|---|
X-FourA-Request-Id |
UUID | Уникальный идентификатор, присвоенный request. Возвращается в каждом response, включая 4xx и 5xx, за исключением случаев, когда FourA вообще не может прочитать тело: 400 Invalid JSON in request body и 413 отклоняются до присвоения ID. Логируйте его на своей стороне. |
X-FourA-Credits |
integer | Кредиты, списанные за этот request. Возвращается в каждом response, достигшем движка, независимо от успеха или ошибки (работа была выполнена в любом случае). Вызов, отклоненный FourA до запуска каким-либо движком (отсутствующий или недействительный ключ, лимит тарифного плана или платформы, отклоненная цель или proxy ID), не содержит этого заголовка. О тарифицируемых исходах читайте в Request Outcomes. |
Этот же request ID связывает предпросмотр полезной нагрузки request и response в Activity Log в Dashboard (хранится 24 часа, последние 200 на ключ). Поэтому вы можете найти нужный request позже и воспроизвести его из Activity прямо в Playground. Укажите его при обращении в поддержку, чтобы найти 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.
Конечные точки
Используете эти endpoint через MCP? Сервер
@fouradata/mcpоборачивает все четыре endpoint как нативные инструменты MCP (foura_auto,foura_single,foura_proxy,foura_browser) с одинаковой структурой входных данных, а также поддержкойoffload_largeдля экономной обработки больших ответов по токенам. Отличия: вfoura_browserнет поляlean, аfoura_proxyпока не принимает поля exit location.
FourA предоставляет четыре request endpoint, каждый из которых оптимизирован под определенный сценарий:
| Endpoint | Лучше всего подходит для |
|---|---|
POST /auto/ |
Умная загрузка (smart fetch). Вы передаете URL, FourA выбирает самый дешевый рабочий путь (ротируемый proxy или браузер, плюс прямой request с forceProxy: false) и запоминает рабочие параметры для каждого хоста. |
POST /single/ |
Быстрые HTTP-запросы, статические страницы, API |
POST /proxy/ |
Защищенные сайты с автоматической ротацией proxy, опциональный выбор страны выхода |
POST /browser/ |
Страницы с рендерингом JavaScript, SPA |
GET /profiles |
Каталог профилей браузеров для single и proxy. Публичный, без API key. |
Подробное руководство по выбору подходящего варианта см. в разделах Choosing the Right Endpoint и Smart Fetch guide.
Ограничения целевого URL
Цели, которые резолвятся в частные, loopback или зарезервированные диапазоны IP (RFC 5735, RFC 6598, зарезервированные блоки IPv6), отклоняются с кодом 400 до того, как request покинет FourA. Пересылаются только публичные имена хостов и IP-адреса.
{ "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." }
Целевой адрес на собственном хосте API FourA (eu.api.foura.ai или api.foura.ai) также отклоняется с кодом 400 на всех четырех endpoint до выполнения запроса или списания средств. URL с пробелом или управляющим символом внутри точно так же отклоняется с кодом 400 в режимах Single, Proxy и Auto; кодируйте пробел как %20 (Browser выполняет выборку так же, как Chrome). Единственная страница на этом хосте, которую загружает FourA, это /inspect.
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
Smart Fetch (Auto)
POST /api/auto/
Вы передаете URL и опциональные правила validate. FourA проходит по возрастающей цепочке с учетом стоимости (ротируемый proxy, затем полноценный browser) и останавливается на первом шаге, вернувшем ответ, подходящий под ваши правила. При forceProxy: false сначала выполняется недорогая прямая проверка. При повторных запросах к тому же хосту воспроизводится готовая теплая session, поэтому второй запрос обходится дешево.
Вам не нужно настраивать повторные попытки, размеры пулов или количество proxy. FourA подбирает их для каждого хоста автоматически.
Тело запроса
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
url |
string | Да | - | Целевой URL |
method |
string | Нет | "GET" |
HTTP-метод |
headers |
[string, string][] | Нет | - | Заголовки для отправки на целевой ресурс в виде пар [name, value]. Отправляются на всех шагах, кроме browser. Переданный вами Cookie доходит до сайта без изменений, а cookie из сохраненной session добавляются рядом с ним только под теми именами, которые вы не передавали. Заголовок userAgent из сохраненной session заменяет ваш User-Agent. На шаге proxy условные заголовки вроде If-None-Match исключаются, если только ваш validate.status.accept не содержит 304. |
data |
any | Нет | - | Тело запроса для методов, отличных от GET |
validate |
object | Нет | - | Критерии успешности в том же формате, что и validate в Single Request (см. ниже). Позволяют алгоритму auto понять, как выглядит реальная страница, и отличить контент от страницы проверки. |
returnSession |
boolean | Нет | true |
Включить успешную 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/. |
followRedirects |
integer | Нет | 5 |
Максимальное количество редиректов для перехода на недорогих шагах цепочки. 0 для отключения. Макс. 20. |
exitClass |
string | Нет | - | standard или premium, аналогично Proxy Request. Значение premium разрешает эскалацию вызова до premium exit, если стандартный пул не может получить доступ к странице. Требуется тарифный план с поддержкой premium exit. См. exitClass в Smart Fetch. |
Ответ
{
"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 |
number | HTTP-статус от целевого ресурса. |
data |
string | Тело response в виде текста, независимо от ступени выполнения. Страница JSON возвращается как текст JSON, поэтому парсить ее нужно самостоятельно. |
headers |
array or object | Заголовки response целевого ресурса. Ступени Single и proxy возвращают массив объектов header для каждого узла пересылки; ступени browser возвращают плоский объект. |
meta.rung |
string | Какая ступень лестницы доставила response. Одно из значений: probe (дешевый прямой request, только с forceProxy: false), proxy (ротируемый proxy), browser (полный рендеринг в браузере), cache (повторно использованная прогретая сессия), warmup (сначала была запрошена входная страница сайта, и ее cookie открыли глубокий URL) или fail (ни одна ступень не вернула принятый response). |
meta.solved |
boolean | Потребовался ли странице дополнительный шаг (страница проверки/challenge), и был ли он успешно пройден во время этого вызова. |
meta.attempts |
number | Количество подпопыток, сделанных до успешного ответа. |
meta.credits |
number | Всего кредитов, списанных за этот вызов. Совпадает с X-FourA-Credits. |
meta.attemptsByEngine |
object | Запросы, отправленные на single, proxy и browser. Request в browser, отклоненный вашим тарифом, засчитывается, так как он был отправлен. |
meta.browserRequests |
number | Запросы browser, использовавшие слот из вашего ежедневного лимита. Request в browser, отклоненный вашим тарифом, ничего не списывает. |
meta.exitClass |
string | Какой класс выхода доставил ответ, присутствует, если в request был указан exitClass: premium или standard. То же значение передается в response header X-FourA-Exit-Class. |
session.proxy |
string | Закодированный ID proxy, доставившего response. Используйте его повторно в request Single или Browser. Присутствует, когда returnSession равен true. |
session.cookies |
array | Файлы cookie для повторного использования, каждый содержит как минимум name и value. Ступень browser возвращает хранилище cookie браузера. Ступень proxy или прямой probe возвращает только те cookie, которые открыли страницу (например, установленные проверочной страницей сайта), но не все cookie, установленные страницей, поэтому список может быть пустым. Присутствует, когда returnSession равен true. |
session.userAgent |
string | User-Agent, использованный в успешной попытке. Присутствует, когда returnSession равен true. |
error |
string | Сообщение об ошибке, если вызов завершился неудачей. |
attemptReport |
object | При неудачном вызове: запросы движка, завершившиеся без получения страницы, сгруппированные по причине. См. Smart Fetch. |
Пример
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 key в каждый подвызов. Вызов Auto считается как один request в вашем Activity Log и на странице Overview, с суммой кредитов всех подвызовов; подвызовы указаны под ним как его попытки и никогда не считаются отдельными requests.
- Передавайте
validate.data.acceptс подстрокой, которую содержит только реальная страница. Без нее auto не сможет отличить настоящий статус 200 от страницы проверки challenge со статусом 200. - Удаленная страница является ответом сайта, а не отказом в обслуживании. Когда две выходные точки возвращают одинаковый
404или410, а вашvalidateего не принимает, вызов завершается с этимstatusи сообщениемerror, которое начинается сthe site answered. Укажите статус вvalidate.status.accept, и Auto вернет первый response с этим статусом, который пройдет остальные проверки вашегоvalidate. То же самое применимо к любому другому указанному там статусу, кроме403,429,503и202, которые сайты также отправляют вместе со страницей challenge. timeout_msограничивает весь вызов целиком. Первый холодный запрос к защищенному сайту может занять десятки секунд; повторно используемые прогретые сессии обычно завершаются быстрее чем за секунду.
exitClass в Smart Fetch
exitClass работает в Smart Fetch так же, как и в Proxy Request: это разрешение, а не строгая инструкция. Auto сначала пробует стандартный пул. Если стандартный пул не может получить доступ к странице, а в request указан premium, Auto открывает страницу в браузере через premium exit. Созданная там сессия обслуживает ваши последующие вызовы к тому же сайту, в которых также указан premium; вызовы без этого параметра ее не используют.
Исчерпание лимита не является ошибкой. Как только premium трафик в вашем тарифном плане израсходован за расчетный период, вызов продолжается через стандартный пул, а meta.exitClass возвращает standard. На тарифе без premium exits вызов, отправляющий exitClass: premium, отклоняется со статусом 403 и кодом X-FourA-Limit: plan_limit_premium еще до начала выполнения какой-либо работы.
Premium трафик измеряется так же, как в Proxy Request. Страница, открытая в браузере, загружает больше данных, чем просто сама страница, поэтому premium страница Smart Fetch расходует больше premium трафика, чем та же страница, полученная через Proxy Request. Чтобы снизить этот объем, premium страница Smart Fetch загружается без изображений, шрифтов и медиа, а также без скриптов известных провайдеров рекламы, аналитики и согласий.
Single Request
POST /api/single/
Отправляет HTTP request с реалистичными сетевыми характеристиками браузера без запуска реального браузера. Это самый быстрый endpoint.
Тело запроса
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
method |
string | Да | - | Метод HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
url |
string | Да | - | Целевой URL. Используйте {ts} в любом месте URL для вставки текущей временной метки с целью сброса кэша. |
headers |
[string, string][] | Нет | - | Пользовательские заголовки в виде пар [name, value] |
unblocker |
boolean | Нет | true |
Отправлять реалистичные браузерные заголовки (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Включено по умолчанию. Установите false, и FourA не будет добавлять браузерные заголовки, оставив только переданные вами. |
timeout_ms |
number | Нет | 15000 | Общий таймаут в мс (макс: 120000) |
connect_timeout_ms |
number | Нет | 5000 | Таймаут соединения в мс |
accept_timeout_ms |
number | Нет | 5000 | Таймаут подтверждения соединения в мс (время ожидания подключения) |
server_response_timeout_ms |
number | Нет | 15000 | Таймаут ответа сервера в мс (время ожидания первого байта) |
dns_cache_timeout_sec |
number | Нет | 120 | TTL кэша DNS в секундах (макс: 240) |
followRedirects |
number | Нет | disabled | Максимальное количество перенаправлений (0-20). Опустите, чтобы отключить. |
tryJsonData |
boolean | Нет | false | Разбирать тело ответа как JSON, если возможно |
returnBuffer |
boolean | Нет | false | Возвращать необработанный буфер вместо декодированной строки |
data |
any | Нет | - | Тело запроса (строка или объект, сериализуется в JSON автоматически) |
proxy |
string | Нет | - | Идентификатор прокси из предыдущего ответа для закрепления того же выходного узла. Передавайте непрозрачную строку без изменений. Прямой адрес прокси отклоняется с ошибкой 400 Invalid proxy format. Некоторые идентификаторы нельзя закрепить: см. Закрепление выходного узла. |
browser |
string | Нет | Chrome | Эмулируемый браузер: Chrome, Edge, Safari, Firefox или Tor. См. Профили браузеров. |
os |
string | Нет | - | Эмулируемая операционная система: Windows, macOS, Android или iOS. Имя семейства включает любую из его версий. |
version |
string | Нет | newest | Эмулируемая версия браузера в соответствии со списком каталога. При наличии нескольких совпадений выбирается самая новая. |
profile |
string | Нет | - | Точный id профиля из GET /api/profiles вместо трех полей выше. |
validate |
object | Нет | - | Правила валидации ответа (см. ниже) |
Профили браузеров
По умолчанию запрос эмулирует последнюю версию Google Chrome. Некоторые ресурсы принимают один браузер и блокируют другой, поэтому browser, os и version фильтруют каталог измеренных профилей, а profile выбирает профиль по id.
{
"method": "GET",
"url": "https://example.com",
"browser": "Firefox",
"os": "Windows"
}
Правила:
- Для выбора требуется
unblocker(включен по умолчанию). Еслиunblockerвыключен, заголовки браузера не отправляются, поэтому запрос отклоняется, а не применяется частично. - Если подходит несколько профилей, выбирается самая новая версия.
- Комбинация, отсутствующая в каталоге, возвращает ошибку со списком доступных вариантов, а неизвестный
profileid возвращаетunknown profile '<id>'. Запрос никогда не отправляется под видом другого браузера. - Эти же четыре поля доступны внутри объекта
requestвPOST /proxy/.
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 status code |
validate.status.fail |
number[] | Отклоняемые HTTP status code |
validate.headers.accept |
object | Response считается успешным, если хотя бы одна пара совпадает на любом шаге redirect. Имена и значения проверяются без учета регистра, по частичному совпадению. |
validate.headers.fail |
object | Пары ключ-значение header, вызывающие ошибку |
validate.data.accept |
string[] | Response считается успешным, если body содержит хотя бы одну из этих строк |
validate.data.fail |
string[] | Строки в response body, вызывающие ошибку |
Пример
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": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
"data": "<!doctype html>...",
"total_time": 0.342
}
Если целевой ресурс выполняет проверку на ботов перед отдачей тела ответа, response также содержит объект 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 со строкой статуса и всеми заголовками ответа. Многозначные заголовки (Set-Cookie, Link, WWW-Authenticate) возвращаются в виде массивов строк. |
data |
string/object | Тело ответа (JSON, если tryJsonData равен true) |
total_time |
number | Общее время выполнения запроса в секундах |
proxy |
string | Закодированный ID прокси, через который прошел запрос (только если в запросе был указан proxy). Используйте его в следующем вызове для привязки к тому же выходному узлу. |
defense |
object | Присутствует, если целевой ресурс выполнил проверку на ботов для этого запроса или если повторная попытка с собственными cookie сайта вернула тело ответа. defense.solved указывает, была ли пройдена проверка, defense.retry показывает, удалось ли получить контент при повторной попытке. Полный список полей и систем см. в Проверки сайта. |
error |
string | Сообщение об ошибке, если запрос завершился неудачно |
Proxy Request
POST /api/proxy/
Маршрутизирует запрос через ротируемые прокси с автоматическим повтором при сбое. Дополнительно позволяет ограничить выбор списком стран выходных узлов, видимых целевому серверу.
Тело запроса
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
request |
object | Да | - | Тело одиночного request (те же поля, что и в Single Request выше) |
timeout_ms |
number | Нет | 45000 | Общий таймаут для всех попыток в мс (макс: 120000) |
maxTries |
number | Нет | 5 | FourA прекращает запуск новых попыток после такого числа неудач (макс: 90). Попытки выполняются параллельно, поэтому завершиться может чуть больше указанного числа. |
ignoreProxies |
string[] | Нет | - | Идентификаторы proxy для исключения из ротации (используйте ID из предыдущих ответов) |
exitCountries |
string[] | Нет | - | Строгий список разрешенных двухбуквенных кодов стран, видимых целевому ресурсу (например, ["CZ", "GB"]). Значения очищаются от пробелов, переводятся в верхний регистр и дедуплицируются. Выходы стандартного пула с неизвестной страной исключаются, и стандартный пул никогда не переключается на незапрошенную страну. Премиум-выход также совершается из одной из указанных стран. |
exitClass |
string | Нет | - | standard или premium. premium позволяет запросу эскалировать до премиум-выхода, если стандартный пул испытывает сложности с защищенной целью. Требуется тарифный план, включающий премиум-выходы. |
exitState |
string | Нет | - | Регион выхода. Требует exitClass: premium и ровно одну страну в exitCountries. См. Exit location. |
exitCity |
string | Нет | - | Город выхода. Требует exitClass: premium и ровно одну страну в exitCountries. |
exitAsn |
string | Нет | - | Сеть выхода по номеру AS, например 8866. Требует exitClass: premium и ровно одну страну в exitCountries. |
exitOs |
string | Нет | - | windows, android, ios или mac: тип устройства, которому принадлежит адрес. Требует exitClass: premium. |
exitLifetimeMin |
integer | Нет | - | Время удержания адреса выходом в минутах, от 3 до 1440. Требует exitClass: premium. |
Область действия exitCountries
Выбор использует последние доступные метаданные страны, видимой целевому ресурсу, которые обычно обновляются примерно раз в десять минут. Это не динамический поиск геолокации во время запроса. Не определяйте обслуживающую страну по адресу хоста proxy.
Если в текущем пуле нет совпадений для запрошенных стран, а в запросе не был указан exitClass: premium, response возвращает HTTP 200 с объектом ошибки:
{
"error": "No eligible proxy found for exit countries: CZ, GB",
"code": "no_eligible_proxy",
"details": { "exitCountries": ["CZ", "GB"] },
"total": 0.084
}
Сохраните запрошенный scope и повторите попытку позже. Изменяйте или расширяйте его только в том случае, если требования вашего рабочего процесса к стране явно изменились.
Пример
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
}
| Поле | Тип | Описание |
|---|---|---|
proxy |
string | Закодированный идентификатор использованного proxy. Используйте его повторно в Single или Browser request, передав в поле proxy, или пропустите его в следующем Proxy request с помощью ignoreProxies. |
exitCountry |
string | Двухбуквенный код страны proxy, видимый целевому серверу, который обработал request. Присутствует только тогда, когда в request было задано exitCountries, независимо от класса использованного выхода. Всегда проверяйте, что это один из запрошенных вами кодов, прежде чем доверять response. |
exitClass |
string | Класс выхода, обработавший этот request. Присутствует в успешном response, если класс был указан в request. Значение premium означает, что тело вернул премиум-выход; standard означает стандартный пул. Неудачный вызов ничего не отдал, поэтому не содержит exitClass; смотрите attemptReport, чтобы узнать, с чем столкнулись попытки. |
total |
number | Общая длительность по астрономическому времени в секундах (float). Включает выбор proxy, повторные попытки и успешную попытку. total_time относится только к внутреннему request; total всегда >= total_time. |
profile |
string | Профиль браузера, выбранный ротацией. Присутствует только в том случае, если он отличается от запрошенного. Отсутствие поля означает, что request был отправлен в точности как указано. Передайте id обратно как profile в последующих вызовах, чтобы сохранить сработавший браузер. |
error |
string | Сообщение об ошибке, если request завершился неудачно. При несовпадении scope code имеет значение no_eligible_proxy, а details.exitCountries дублирует нормализованный scope. |
attemptReport |
object | Присутствует в каждом неудачном вызове Proxy. Подсчитывает, с чем столкнулись попытки, чтобы заблокированный пул, неработающий пул и не сработавшее правило validate не выглядели как одна и та же ошибка. См. ниже. |
request |
object | Присутствует в неудачном вызове Proxy: request, который выполнил FourA, с заполненными значениями по умолчанию и вашими ignoreProxies в исходном виде. |
Все поля response из Single Request также включены, включая defense: попытка через proxy, столкнувшаяся с проверкой на ботов, сообщает об этом так же, как и Single.
Причины сбоя вызова Proxy
Download maxTry limit reached выглядит одинаково независимо от исхода попыток, поэтому каждый неудачный response Proxy содержит attemptReport рядом с ошибкой:
{
"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
}
| Поле | Тип | Описание |
|---|---|---|
total |
integer | Количество предпринятых попыток |
noResponse |
integer | Выходной узел не ответил, целевой сайт не был достигнут |
defense |
integer | Сайт ответил, в ответе обнаружена проверка на бота |
contentRejected |
integer | HTTP 200, проверки на бота нет, отклонено только вашим validate.data |
statusRejected |
integer | Сайт ответил, проверки на бота нет, отклонено вашим validate.status |
other |
integer | Ответ получен, но ни один из указанных выше случаев не подошел |
vendors |
string[] | Вендоры систем защиты от ботов, обнаруженные в ходе выполнения задачи |
profilesTried |
string[] | Профили браузера, отправленные задачей, в порядке первого использования. default означает, что ваш request ушел без изменений. |
summary |
string | Одно предложение на основе счетчиков, безопасное для логирования |
Строка error не изменяется, поэтому логика клиента, завязанная на нее, продолжает работать. Что делать с каждым из счетчиков: Почему у proxy request закончились попытки.
exitClass
Некоторые цели блокируют выходные узлы из стандартного пула независимо от числа попыток. exitClass: premium разрешает Proxy передавать такой request на premium exit в дополнение к стандартному пулу, а не только перебирать адреса внутри него.
{
"exitClass": "premium",
"request": { "method": "GET", "url": "https://example.com/report" }
}
Перед отправкой важно знать три вещи.
Это разрешение, а не жесткая инструкция. Стандартный пул по-прежнему пытается обработать запрос первым, и обычно он справляется быстрее. Премиум exit подключается только тогда, когда пул исчерпал короткий лимит времени на запрос или целевой ресурс явно отклонил его. Запрос, на который стандартный пул ответил до попытки использовать премиум exit, считается обычным успехом и не расходует премиум трафик. Как только премиум exit был опробован, его трафик учитывается, как описано ниже.
Премиум exit соблюдает exitCountries. Если указан список стран, премиум exit выбирается из одной из них, и заголовок exitCountry в response указывает ее, как и для стандартного пула.
Response сообщает, что именно обработало запрос. Когда вы указываете класс, response возвращает exitClass:
{
"status": 200,
"exitClass": "premium",
"proxy": "Y2QXVK",
"data": "..."
}
premium означает, что тело ответа вернул премиум-выход. standard означает, что использовался стандартный пул. Этот же ответ возвращается, когда премиум-выход получить не удалось, а также когда премиум-трафик вашего тарифного плана (плюс купленный дополнительно) исчерпан за расчетный период. Ни то, ни другое не считается ошибкой, и вы можете сверять расход премиум-трафика по каждому запросу, а не по месячному показателю. Это же значение передается в заголовке ответа X-FourA-Exit-Class (см. Response Headers).
Премиум-трафик измеряется на уровне сети. Премиум-попытка учитывает отправленные и полученные байты при их передаче по сети, включая сжатие и шифрование, независимо от того, вернула ли она запрошенную страницу. Попытка, которая продолжала выполняться, когда ответил другой выход, немедленно останавливается, а переданный ею до этого момента трафик также засчитывается. Премиум-трафик учитывается в вашей премиум-квоте, а также входит в общий объем трафика: одни и те же байты отображаются дважды, но не суммируются между собой. Если страницу отдал премиум-выход, его трафик составляет весь трафик запроса, поэтому страница повторно как стандартный трафик не учитывается. Страница Usage & Limits показывает общий трафик, долю премиум-трафика и доступный премиум-лимит.
Пропуск поля и отправка standard оставляют запрос в стандартном пуле: только premium разрешает премиум-выход. Успешный запрос с указанием класса получает в ответе exitClass, а запрос без этого поля не получает его.
Исчерпание лимита не является ошибкой. Запрос с указанием premium после исчерпания лимита продолжает работать: его обслуживает стандартный пул, а ответ содержит standard. Единственное исключение, это запрос, в котором указана exit location: стандартный пул не может ее предоставить, поэтому запрос отклоняется.
Для exitClass: premium требуется тарифный план с поддержкой премиум-выходов. На тарифе без них запрос никогда не расходует премиум-выход: он отклоняется с кодом 403 и ошибкой X-FourA-Limit: plan_limit_premium (см. Rate Limits) до начала какой-либо обработки.
Локация выхода
Премиум-выход может подключаться из конкретной точки внутри страны и сохранять свой адрес столько времени, сколько вам требуется:
{
"exitClass": "premium",
"exitCountries": ["BG"],
"exitCity": "sofia",
"exitLifetimeMin": 15,
"request": { "method": "GET", "url": "https://example.com/" }
}
В response указаны exit и страна выхода:
{
"status": 200,
"exitClass": "premium",
"exitCountry": "BG",
"proxy": "1EM4GZY",
"data": "..."
}
Этот ID proxy сохраняет все эти параметры. Передайте его в Single или Browser, и request уйдет из того же места без указания других полей. См. Pinning an Exit.
Правила:
- Любое из полей
exitState,exitCity,exitAsn,exitOsиexitLifetimeMinотправляет request только через премиум-выходы. Стандартный пул не используется, так как он не поддерживает эти параметры. - Для них требуется
exitClass: premium. Без этого поля request отклоняется с кодом 400 и указанием имени поля. exitState,exitCityиexitAsnсуществуют внутри одной страны, поэтому для них требуется ровно одна страна вexitCountries. ПоляexitOsиexitLifetimeMinдопускают несколько стран: выход берет одну из них, аexitCountryв response сообщает, какую именно.- Для
exitState,exitCity,exitAsnиexitOsтребуется тарифный план с геотаргетингом и премиум-выходами. - Если премиум-трафик исчерпан, request отклоняется с кодом 403 и ошибкой
X-FourA-Limit: plan_limit_premium, поскольку стандартный пул не может его обработать. - Если для этого региона нет доступного премиум-выхода, в response возвращается конверт ошибки, аналогичный описанному в exitCountries scoping, с ошибкой
No premium exit answered for this requestиcode: no_eligible_proxy. Значениеdetails.exitCountriesпередается, если был отправлен список стран.
Эти параметры соответствуют значениям, которые proxy port принимает для state, city, asn и os.
Ротация профилей браузера
Proxy выполняет ротацию выходов. Если сайт блокирует не сам выход, а профиль браузера, предоставленный FourA, Proxy также переключается на другое семейство браузеров из каталога. Это не добавляет новых попыток: ротация меняет данные, отправляемые при повторе, но не влияет на факт его выполнения.
Proxy также запоминает на некоторое время семейство, которое сайт принял в последний раз, поэтому последующий вызов к тому же сайту может начаться с этого семейства вместо значения по умолчанию. Response указывает его в profile, как и для любого семейства, выбранного ротацией.
Явно заданные profile, browser, os или version во внутреннем объекте request никогда не перезаписываются, как и request с собственным заголовком User-Agent или Cookie, поскольку авторизация привязана к сигнатуре, с которой она была получена.
Запрос браузера
POST /api/browser/
Открывает ваш URL в экземпляре браузера Chrome. Страница загружается, выполняется JavaScript, и вы получаете полностью отрендеренный HTML вместе с cookie jar.
Тело запроса
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
url |
string | Да | - | Целевой URL |
headers |
object | Нет | - | Пользовательские headers в виде пар ключ-значение |
cookies |
array | Нет | - | Список cookie: [{name, value, domain?}] |
userAgent |
string | Нет | - | Пользовательская строка User-Agent |
unblocker |
boolean | Нет | true |
Выполняет проверку, запрашиваемую страницей перед загрузкой (challenge-страница или аналогичный шлюз). Включено по умолчанию. Установите false, чтобы отобразить исходный ответ страницы без изменений, включая challenge-страницу. |
proxy |
string | Нет | - | ID proxy из предыдущего response для закрепления той же точки выхода. Передавайте неизмененную строку. Прямой адрес proxy отклоняется с ошибкой 400 Invalid proxy format. |
timeout_ms |
number | Нет | 30000 | Таймаут загрузки страницы в мс (макс: 120000) |
checkStatus |
number | Нет | - | Ожидаемый HTTP-статус (при несовпадении request завершается с ошибкой) |
checkText |
string | Нет | - | Текст, который должен присутствовать на отрендеренной странице |
lean |
boolean | Нет | false |
Блокирует изображения, шрифты, медиа и запросы к известным сервисам рекламы, аналитики, согласий и соцсетей. Сама страница, ее скрипты, стили и элементы, необходимые для проверок, продолжают загружаться. Используйте для снижения трафика, например, при работе через закрепленный премиум-выход. |
Синхронизация системного времени браузера с точкой выхода
Страница может считывать часовой пояс браузера и сравнивать его со страной IP-адреса, который она видит. Несоответствие часового пояса является одним из самых простых сигналов для систем защиты от ботов, и его устранение не требует дополнительных затрат.
Вам не нужно ничего настраивать. FourA определяет страну по proxy ID, а браузер передает соответствующий ей часовой пояс.
- Учитывается страна выхода, то есть страна, которую видит целевой сервер, а не место размещения proxy-сервера. Эти локации часто различаются, что критично для проверок.
- Если FourA не может определить страну выхода, системное время браузера остается без изменений, исключая случайные значения. Премиум-выход имеет известную страну, если она была запрошена через
exitCountriesв Proxy Request. - Синхронизируется только часовой пояс.
Accept-Languageи отдаваемый сайтом контент остаются неизменными, поэтому страница не переключит язык автоматически.
Параметр userAgent
Передайте userAgent, и именно эту строку увидят страница, ее workers и целевой сервер. FourA также формирует на ее основе соответствующие client hints (sec-ch-ua, sec-ch-ua-platform, navigator.platform и высокоэнтропийные значения, запрашиваемые детектором), предотвращая расхождение данных между заголовками request и JavaScript.
Параметр userAgent в response показывает фактически переданное значение. Это важно при повторном использовании данных прохождения проверок: cookie cf_clearance привязан к точке выхода и User-Agent, на котором он был получен. Передавайте обратно строку, указанную в response, а не исходное расчетное значение. См. раздел Site checks.
Отправьте строку не от Chromium (например, User-Agent Firefox), и она будет передана как есть, без добавления списка брендов Chromium.
Пример
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"]}
}
| Поле | Тип | Описание |
|---|---|---|
status |
number | Код состояния HTTP от целевого сервера |
headers |
object | Заголовки ответа |
body |
string or object | Полностью отрендеренное содержимое страницы. Строка HTML, если content-type является HTML; объект, если страница вернула JSON и он был автоматически распарсен. |
cookies |
array | Полные объекты cookie со страницы. Каждый cookie включает name, value, domain, path, expires, httpOnly, secure, sameSite и другие свойства cookie. |
userAgent |
string | Использованный User-Agent браузера |
defenseSolved |
boolean | true, если защита от ботов была обнаружена и успешно пройдена в этом вызове; иначе false. Определяет, стоит ли вызов 5 или 10 кредитов. |
defenses |
object | present перечисляет всех вендоров, распознанных при загрузке страницы, cleared содержит тех, чье подтверждение прохождения сохранено на итоговой странице. Вендор может появиться в present и отсутствовать в cleared. См. Site checks. |
proxy |
string | Закодированный ID прокси, через который прошел запрос (только если proxy был передан в запросе). Используйте его повторно в последующих вызовах, чтобы сохранить ту же точку выхода. |
error |
string | Сообщение об ошибке, если запрос завершился неудачно |
Закрепление точки выхода
Значение proxy в запросе Single или Browser закрепляет точку выхода, использованную в предыдущем вызове. Передавайте непрозрачный ID в точности так, как он был получен, и никогда не используйте адрес прокси. ID из запроса Proxy, где были указаны страна, локация или время жизни, сохраняет эти параметры, поэтому закрепленному запросу не требуются другие поля.
Три значения отклоняются с кодом 400:
| Ошибка | Значение |
|---|---|
Invalid proxy format |
Значение не является ID, выданным FourA. Прямой адрес прокси приводит к этой ошибке. |
Proxy not found |
ID декодирован, но больше не указывает на активную точку выхода. Получите новый ID из свежего вызова. |
Managed exit: this proxy id cannot be pinned to a request |
Точка выхода существует, но FourA не может удерживать ее открытой для именованного запроса. ID премиум-выхода приводит к этой ошибке, если в вашем тарифе не осталось премиум-трафика. Используйте повторно сессию, в которой он был получен, или выполните вызов через POST /api/proxy/ и примите любую выбранную им точку выхода. |
Закрепленный премиум-выход тарифицируется как премиум-трафик. Ответ содержит X-FourA-Exit-Class: premium для отслеживания по каждому запросу, а переданный точкой выхода трафик учитывается в объеме премиум-трафика на странице Usage & Limits и в общем объеме полосы пропускания, независимо от того, вернул ли сайт нужную страницу. Для закрепления требуются доступные премиум-выходы в тарифе и остаток лимита; в противном случае ID отклоняется с описанной выше ошибкой 400 для управляемой точки выхода.
Коды состояния HTTP
| Код | Значение |
|---|---|
| 200 | Запрос выполнен (проверьте внутренний status для ответа целевого ресурса) |
| 400 | Недопустимое тело запроса, параметры, целевой IP в частном/зарезервированном диапазоне, обращение к собственному API-хосту FourA, URL с незакодированным пробелом (Single, Proxy, Auto) или proxy ID, который нельзя закрепить. В Single, Proxy и Browser поле, не прошедшее валидацию, указывается в Invalid request: <field>: <reason> (до пяти полей). Не тарифицируется. Auto отвечает на ту же ошибку кодом HTTP 200 и status: 400 в теле. |
| 401 | Отсутствует или недействителен API-ключ |
| 403 | Endpoint или параметр не входит в ваш тарифный план. X-FourA-Limit указывает причину: plan_limit_feature или plan_limit_premium. |
| 404 | Not Found: по этому пути нет endpoint. |
| 413 | Тело JSON-запроса превышает 100 КБ. Ответ не является JSON и не содержит X-FourA-Request-Id. |
| 429 | Лимит тарифного плана (установлен заголовок X-FourA-Limit) или общий поминутный лимит платформы (без заголовка) |
| 500 | Внутренняя ошибка сервера |
| 502 | Upstream unavailable: FourA не удалось подключиться к своему движку. Malformed JSON from backend: движок ответил, но FourA не удалось прочитать ответ. Повторите попытку. |
| 503 | Сервис временно отключен или перегружен, API key check temporarily unavailable, если FourA временно не удалось проверить ваш ключ (повторите попытку через Retry-After), или Backend service unavailable во время перезапуска движка. В Browser страница ждет свободный браузер до 10 секунд, если все они заняты, и возвращает Backend service unavailable, если за это время ничего не освободилось. |
| 504 | Upstream timeout. Движок не успел завершить работу в рамках лимита времени на этот запрос. Увеличьте timeout_ms или повторите попытку. |
Дальнейшие шаги
- Smart Fetch (Auto): когда позволить FourA выбрать путь за вас
- Выбор подходящего endpoint: когда выбирать Single, Proxy или Browser вручную
- Аутентификация: управление вашими API-ключами
- Обработка ошибок: корректная обработка ошибок
- Проверки сайтов: чтение поля
defenseи повторное использование clearance - Почему в прокси-запросе закончились попытки: чтение
attemptReportи действия на его основе - Ограничения частоты запросов: подробнее о лимитах запросов
- Быстрый старт: ваш первый запрос за 30 секунд