Справочник 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 выключен, заголовки браузера не отправляются, поэтому запрос отклоняется, а не применяется частично.
  • Если подходит несколько профилей, выбирается самая новая версия.
  • Комбинация, отсутствующая в каталоге, возвращает ошибку со списком доступных вариантов, а неизвестный profile id возвращает 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 или повторите попытку.

Дальнейшие шаги

Обновлено: 13 ноября 2026 г.