Справочник endpoint API

Справочник по всем endpoint FourA API с параметрами request и форматами response.

Базовый URL

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

Аутентификация

Для каждого request требуется ваш 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. Keys используют префикс pk_live_.

Response Headers

Responses от /api/* содержат два correlation headers:

Header	Value	Description
`X-FourA-Request-Id`	UUID	Уникальный ID, назначенный request. Возвращается в каждом response, включая 4xx и 5xx, кроме случаев, когда FourA вообще не может прочитать body: `400 Invalid JSON in request body` и `413` отклоняются до назначения ID. Логируйте его на своей стороне.
`X-FourA-Credits`	integer	Credits, списанные за этот request. Возвращается в каждом response, дошедшем до движка, успешно или с ошибкой (работа была выполнена в обоих случаях). Вызов, отклоненный FourA до запуска движка (отсутствующий или недействительный key, лимит плана или платформы, отклоненный target или proxy ID), его не содержит. См. Request Outcomes для информации о тарифицируемых исходах.

Тот же request ID служит ключом для предпросмотра payload запроса и ответа в Activity Log в Dashboard (хранятся 24 часа, последние 200 на key). Вы можете найти точный 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.

Endpoints

Используете эти endpoint через MCP? Сервер @fouradata/mcp оборачивает все четыре endpoint как нативные MCP tools (foura_auto, foura_single, foura_proxy, foura_browser) с теми же входными параметрами, а также поддерживает offload_large для экономной обработки больших ответов по токенам.

FourA предоставляет четыре request endpoint, каждый из которых оптимизирован под определенный сценарий:

Endpoint	Назначение
`POST /auto/`	Smart fetch. Вы передаете URL, FourA выбирает самый дешевый рабочий путь (direct, rotated proxy или browser) и запоминает рабочий вариант для каждого хоста.
`POST /single/`	Быстрые HTTP requests, статические страницы, API
`POST /proxy/`	Защищенные сайты с автоматической ротацией proxy, опциональный выбор страны
`POST /browser/`	Страницы с рендерингом JavaScript, SPA
`GET /profiles`	Каталог профилей браузеров для `single` и `proxy`. Публичный, без API key.

Подробное руководство по выбору endpoint см. в 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." }

Smart Fetch (Auto)

POST /api/auto/

Вы передаете URL и опциональные правила validate. FourA проходит по оптимизированной по стоимости цепочке (дешевый прямой опрос, ротируемый proxy, полноценный браузер) и останавливается на первом шаге, который возвращает ответ, соответствующий вашим правилам. При повторных запросах к тому же хосту воспроизводится готовая сессия, поэтому следующий запрос стоит дешевле.

Вам не нужно настраивать повторные попытки, размеры пулов или количество proxy. FourA подбирает их для каждого хоста автоматически.

Request Body

Параметр	Тип	Обязательный	По умолчанию	Описание
`url`	string	Да	-	Целевой URL
`method`	string	Нет	`"GET"`	HTTP-метод
`headers`	[string, string][]	Нет	-	Пользовательские headers в виде пар [name, value]
`data`	any	Нет	-	Тело request для методов, отличных от GET
`validate`	object	Нет	-	Критерии успеха, аналогичные `validate` в Single Request (см. ниже). Укажите режиму auto признаки корректной страницы, чтобы отличить контент от страницы с проверкой CAPTCHA.
`returnSession`	boolean	Нет	`true`	Включить успешную сессию (`proxy`, `cookies`, `userAgent`) в response для повторного использования через `/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`.

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

Поле	Тип	Описание
`status`	number	HTTP-статус от целевого ресурса.
`data`	string	Тело ответа в виде текста, независимо от уровня лестницы. Страница JSON возвращается как текст JSON, выполните парсинг самостоятельно.
`headers`	array или object	Заголовки ответа целевого ресурса. Уровни single и proxy возвращают массив объектов заголовков для каждого хопа, уровни browser возвращают плоский объект.
`meta.rung`	string	Уровень лестницы, доставивший ответ. Одно из значений: `probe` (недорогой прямой запрос), `proxy` (ротируемый proxy), `browser` (полный рендеринг в браузере), `cache` (воспроизведена прогретая сессия), `warmup` (сначала была запрошена входная страница сайта, а ее cookies открыли глубокий URL) или `fail` (ни один уровень не вернул принятый ответ).
`meta.solved`	boolean	Потребовался ли странице дополнительный шаг (страница проверки) и был ли он успешно пройден во время этого вызова.
`meta.attempts`	number	Количество промежуточных попыток до успешного выполнения.
`meta.credits`	number	Общее количество кредитов, потраченных на этот вызов. Соответствует `X-FourA-Credits`.
`session.proxy`	string	Закодированный ID proxy, доставившего ответ. Можно использовать повторно в запросах Single или Browser. Присутствует, если `returnSession` имеет значение `true`.
`session.cookies`	array	Cookies из успешной попытки. Присутствует, если `returnSession` имеет значение `true`.
`session.userAgent`	string	User-Agent, использованный в успешной попытке. Присутствует, если `returnSession` имеет значение `true`.
`error`	string	Сообщение об ошибке, если вызов завершился неудачно.

Пример

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

Примечания

Auto выполняет роль координатора. Он вызывает Single, Proxy или Browser внутри себя и передает ваш API key в каждый подвызов. Вызов Auto считается как один request в вашем Activity Log и на странице Overview с суммой кредитов всех подвызовов; сами подвызовы отображаются под ним как попытки и никогда не учитываются как отдельные requests.
Передавайте validate.data.accept с подстрокой, которую содержит только реальная страница. Без этого auto не сможет отличить настоящий 200 от страницы проверки challenge со статусом 200.
timeout_ms ограничивает время выполнения всего вызова. Первый холодный запрос к защищенному сайту может занять десятки секунд; повторно используемые прогретые сессии обычно завершаются менее чем за секунду.

Single Request

POST /api/single/

Отправляет HTTP request с реалистичными сетевыми характеристиками браузера без запуска реального browser. Это самый быстрый endpoint.

Request Body

Параметр	Тип	Обязательный	По умолчанию	Описание
`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` для отправки простой сигнатуры клиента.
`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	Нет	-	ID proxy из предыдущего ответа для закрепления того же выходного узла. Передавайте неизменяемую строку без изменений. Прямой адрес proxy будет отклонен с ошибкой `400 Invalid proxy format`. Некоторые ID нельзя закрепить: смотрите Pinning an exit.
`browser`	string	Нет	Chrome	Эмулируемый браузер: Chrome, Edge, Safari, Firefox или Tor. Смотрите Browser profiles.
`os`	string	Нет	-	Эмулируемая операционная система: Windows, macOS, Android или iOS. Имя семейства допускает любую из его версий.
`version`	string	Нет	newest	Эмулируемая версия браузера в соответствии с каталогом. При наличии нескольких подходящих вариантов выбирается самая новая версия.
`profile`	string	Нет	-	Точный ID профиля из `GET /api/profiles` вместо трех полей выше.
`validate`	object	Нет	-	Правила валидации ответа (см. ниже)

Browser profiles

По умолчанию запрос использует последнюю версию Google Chrome. Некоторые целевые ресурсы принимают один браузер и отклоняют другой, поэтому browser, os и version фильтруют каталог замеренных профилей, а profile выбирает профиль по ID.

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

Правила:

Для выбора требуется unblocker (включено по умолчанию). Если unblocker отключен, заголовки браузера не отправляются, поэтому запрос отклоняется, а не применяется частично.
Если подходят несколько профилей, выбирается самая новая версия.
Если комбинация отсутствует в каталоге, возвращается ошибка со списком доступных вариантов. Запрос никогда не отправляется от имени другого браузера.
Те же четыре поля доступны внутри объекта 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-коды состояния, которые следует принимать
`validate.status.fail`	number[]	HTTP-коды состояния, которые следует отклонять
`validate.headers.accept`	object	Пары ключ-значение заголовков, которые должны присутствовать
`validate.headers.fail`	object	Пары ключ-значение заголовков, вызывающие сбой
`validate.data.accept`	string[]	Строки, которые должны присутствовать в теле ответа
`validate.data.fail`	string[]	Строки в теле ответа, вызывающие сбой

Пример

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'

Ответ:

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

Если целевой ресурс выполняет проверку на ботов перед отдачей тела страницы, 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` показывает, удалось ли получить контент при повторной попытке. См. Site checks для описания всех полей и полного списка систем.
`error`	string	Сообщение об ошибке, если запрос завершился неудачно

Proxy Request

POST /api/proxy/

Направляет ваш запрос через ротируемые прокси с автоматическим повтором при сбое. Опционально можно ограничить выбор набором стран выходных узлов, видимых целевому серверу.

Request Body

Параметр	Тип	Обязательный	По умолчанию	Описание
`request`	object	Да	-	Тело одиночного запроса (те же поля, что и в Single Request выше)
`timeout_ms`	number	Нет	45000	Общий таймаут для всех попыток в мс (макс.: 120000)
`maxTries`	number	Нет	5	Максимальное количество попыток ротации прокси (макс.: 90)
`ignoreProxies`	string[]	Нет	-	ID прокси для исключения из ротации (используйте ID, полученные в предыдущих ответах)
`exitCountries`	string[]	Нет	-	Строгий белый список двухбуквенных кодов стран, видимых целевому серверу (например, `["CZ", "GB"]`). Значения очищаются от пробелов, переводятся в верхний регистр и дедуплицируются. Прокси с неизвестным расположением выхода исключаются, и запрос никогда не переключается на незапрошенную страну.
`exitClass`	string	Нет	-	`standard` или `premium`. `premium` позволяет запросу переключиться на премиум-выход, когда стандартный пул испытывает трудности с защищенной целью. Требуется тарифный план, включающий премиум-выходы.

Ограничение exitCountries

При выборе используются последние доступные метаданные о стране, видимой целевому серверу, которые обычно обновляются примерно за десять минут. Это не динамический поиск геолокации во время запроса. Не определяйте обслуживающую страну по адресу хоста прокси.

Если в текущем пуле нет совпадений для запрошенных стран, ответ возвращает 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` означает, что body вернул 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` без совпадений не отображаются как одна и та же ошибка. См. ниже.

Все поля response для Single Request также включены, среди них defense: попытка через proxy, встретившая проверку на бота, сообщает об этом так же, как и Single.

Причины сбоя Proxy Call

Download maxTry limit reached выглядит одинаково независимо от исхода попыток, поэтому каждый неудачный Proxy response содержит 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-запроса закончились попытки.

exitClass

Некоторые целевые ресурсы отклоняют выходные узлы из стандартного пула независимо от числа попыток. exitClass: premium указывает Proxy на возможность перенаправить такой request на premium exit в дополнение к стандартному пулу, вместо простой ротации внутри него.

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

Перед отправкой стоит учесть три момента.

Это разрешение, а не инструкция. Стандартный пул все равно пытается обработать запрос первым, и обычно он справляется быстрее. Premium exit подключается только тогда, когда пул израсходовал небольшой лимит попыток на запрос или целевой ресурс явно отклонил его. Запрос, на который стандартный пул ответил до попытки использования premium exit, считается обычным успехом и не расходует premium traffic. Как только premium exit был опробован, его трафик учитывается согласно описанию ниже.

Response сообщает, что именно обработало запрос. При указании класса response возвращает exitClass:

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

premium означает, что тело ответа вернул премиум-выход. standard означает, что использовался стандартный пул. Этот же ответ вы получаете, если премиум-выход не удалось получить, или если включенный в тариф премиум-трафик (плюс купленный дополнительно) израсходован за расчетный период. Ни один из этих случаев не является ошибкой, и вы можете сверять свой премиум-трафик по каждому request отдельно, а не только по итогам месяца. То же значение передается в response header X-FourA-Exit-Class (см. Response Headers).

Премиум-трафик измеряется на уровне сети. Премиум-попытка учитывает отправленные и полученные данные при прохождении через сеть в сжатом и зашифрованном виде, независимо от того, вернула ли она страницу. Попытка, которая еще выполнялась, когда ответил другой выход, немедленно останавливается и не учитывается. Премиум-трафик идет в зачет вашего лимита премиума и суммарного bandwidth: одни и те же байты, отображаемые дважды, не суммируются. Когда страницу доставил премиум-выход, его трафик составляет весь трафик request, поэтому страница не учитывается повторно как стандартный трафик. Ваша страница Usage & Limits показывает общий трафик, его премиум-долю и лимит премиума, по которому ведется расчет.

Пропуск поля не тождественен отправке standard. Пропуск оставляет решение неопределенным; отправка standard прямо указывает, что данный request никогда не должен эскалироваться, что позволяет полностью исключить конкретную задачу из премиум-трафика.

Исчерпание лимита не является ошибкой. Request, указывающий premium после исчерпания лимита, продолжает работать: его обслуживает стандартный пул, а response содержит standard. Задачи не останавливаются из-за исчерпанного лимита.

exitClass: premium требует тариф, включающий премиум-выходы. На тарифе без них request никогда не тратит премиум-выход: он либо отклоняется с кодом 403 и заголовком X-FourA-Limit: plan_limit_premium (см. Rate Limits), либо обслуживается из стандартного пула со значением exitClass: standard в response. Обрабатывайте оба варианта.

Browser Profile Rotation

Proxy выполняет ротацию выходов. Если сайт отклоняет браузер, предоставленный FourA, а не сам выход, Proxy переключается на другое семейство браузеров из каталога. Дополнительная попытка не создается: ротация меняет только данные повторной отправки, но не факт ее выполнения.

Proxy также на некоторое время запоминает семейство, которое сайт принял в прошлый раз, чтобы последующий вызов к тому же сайту сразу начинался с этого семейства, а не с варианта по умолчанию. Response указывает его в profile, как и для любого семейства, выбранного ротацией.

Явные profile, browser, os или version во внутреннем request никогда не перезаписываются, как и request с собственным header User-Agent или Cookie, поскольку clearance привязан к сигнатуре, которой он был получен.

Browser Request

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	Нет	-	Идентификатор proxy из предыдущего ответа для закрепления того же узла выхода. Передайте непрозрачную строку обратно без изменений. Необработанный адрес proxy отклоняется с ошибкой `400 Invalid proxy format`.
`exitCountry`	string	Нет	-	Двухбуквенный код страны (ISO 3166-1 alpha-2), через которую отправляется request. Устанавливает системные часы браузера в соответствующий часовой пояс. См. раздел Синхронизация часов браузера с узлом выхода.
`timeout_ms`	number	Нет	30000	Таймаут загрузки страницы в мс (максимум: 120000)
`checkStatus`	number	Нет	-	Ожидаемый HTTP-статус (запрос завершается с ошибкой, если статус отличается)
`checkText`	string	Нет	-	Текст, который обязательно должен присутствовать на отрендеренной странице

Синхронизация часов браузера с узлом выхода

Страница может считывать часовой пояс браузера и сравнивать его со страной обнаруженного IP. Несовпадение является одним из самых простых сигналов для систем защиты от ботов, и его устранение не требует дополнительных затрат.

Укажите в exitCountry страну, через которую идет ваш трафик, и браузер будет передавать соответствующий ей часовой пояс:

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

Правила:

Значение представляет собой страну выхода (exit country), то есть страну, которую видит целевой ресурс, а не место размещения proxy. Они различаются достаточно часто, чтобы это имело значение.
Если параметр опущен, FourA использует страну выхода, когда она известна, а в противном случае оставляет системное время браузера без изменений, чтобы не угадывать.
Нераспознанный код страны обрабатывается так же, как и пропуск поля. Это не считается ошибкой.
Стране соответствуют только системные часы. Accept-Language и контент, отдаваемый сайтом, остаются без изменений, поэтому страница неожиданно не сменит язык.

Параметр `userAgent`

Передайте userAgent, и именно эту строку увидят страница, ее workers и целевой ресурс. FourA также формирует на ее основе соответствующие client hints (sec-ch-ua, sec-ch-ua-platform, navigator.platform и высокоэнтропийные значения, запрашиваемые детектором по имени), поэтому request не будет указывать на один браузер в header и на другой в JavaScript.

Значение userAgent в response указывает на фактически переданный вариант. Это важно при повторном использовании clearance: 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"]},
  "proxy": "A1B2C3"
}

Поле	Тип	Описание
`status`	number	HTTP-код статуса от целевого сервера
`headers`	object	Заголовки ответа (response headers)
`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`, если в этом вызове была обнаружена и успешно пройдена защита от ботов. В противном случае отсутствует. Определяет, стоит ли вызов 5 или 10 кредитов.
`defenses`	object	`present` перечисляет всех вендоров, распознанных во время загрузки страницы, а `cleared` перечисляет тех, чью проверку итоговая страница прошла. Вендор может присутствовать в `present` и отсутствовать в `cleared`. См. Проверки сайта.
`proxy`	string	Закодированный ID прокси, через который прошел запрос (только если в запросе был передан `proxy`). Используйте его повторно в последующих вызовах, чтобы сохранить тот же выходной узел.
`error`	string	Сообщение об ошибке, если запрос не удался

Закрепление выходного узла (Exit Pinning)

Значение proxy в запросе Single или Browser закрепляет выходной узел, использованный в предыдущем вызове. Передавайте непрозрачный ID в точности так, как он был получен, но никогда не передавайте прямой адрес прокси.

Три значения отклоняются с кодом 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 для отслеживания по каждому запросу, а переданный узлом трафик учитывается в объеме премиум-трафика на странице Использование и лимиты, а также в общем объеме трафика, независимо от того, вернул ли сайт нужную страницу. Для закрепления требуются доступные премиум-узлы в тарифном плане и неизрасходованный лимит; в противном случае ID отклоняется с описанной выше ошибкой 400 managed-exit.

Коды состояния HTTP

Код	Значение
200	Запрос выполнен (проверьте внутренний `status` для ответа целевого ресурса)
400	Неверное тело запроса, параметры, целевой IP в приватном/зарезервированном диапазоне или ID прокси, который невозможно закрепить
401	API key отсутствует или недействителен
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`) или общий поминутный лимит платформы (без header)
500	Внутренняя ошибка сервера
502	`Upstream unavailable`. FourA связался со своим движком, но ответ оказался непригодным. Повторите запрос.
503	Сервис временно отключен, перегружен или `Backend service unavailable` во время перезапуска движка
504	`Upstream timeout`. Движок не уложился в отведенный лимит времени для этого запроса. Увеличьте `timeout_ms` или повторите попытку.

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

Smart Fetch (Auto): когда стоит доверить выбор пути FourA
Выбор подходящего endpoint: когда выбирать Single, Proxy или Browser вручную
Аутентификация: управление вашими API keys
Обработка ошибок: корректная обработка ошибок
Проверки сайта: чтение поля defense и повтор прохождения проверки
Почему закончились попытки proxy-запроса: чтение attemptReport и дальнейшие действия
Rate Limits: подробнее о лимитах запросов
Быстрый старт: ваш первый запрос за 30 секунд

Обновлено: 30 сентября 2026 г.

Справочник endpoint API

Базовый URL

Аутентификация

Response Headers

Endpoints

Ограничения целевых URL

Smart Fetch (Auto)

Request Body

Response

Пример

Примечания

Single Request

Request Body

Browser profiles

Правила валидации

Пример

Proxy Request

Request Body

Ограничение exitCountries

Пример

Причины сбоя Proxy Call

exitClass

Browser Profile Rotation

Browser Request

Тело запроса

Синхронизация часов браузера с узлом выхода

Параметр userAgent

Пример

Закрепление выходного узла (Exit Pinning)

Коды состояния HTTP

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

Параметр `userAgent`