Документация › Справка API › Справочник endpoint API

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

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

Базовый URL

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

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

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

Заголовки ответа

Каждый ответ от /api/* содержит два заголовка корреляции:

Заголовок Значение Описание
X-FourA-Request-Id UUID Уникальный ID, присвоенный запросу. Возвращается в каждом ответе, включая ошибки 4xx и 5xx. Логируйте его на своей стороне.
X-FourA-Credits integer Кредиты, потраченные на этот запрос. Возвращаются при успехе и при сбое (работа была выполнена в любом случае). См. Результаты запросов, чтобы узнать, какие результаты тарифицируются.

Тот же ID запроса связывает запрос и превью полезной нагрузки ответа в Журнале активности Дашборда (хранится 24 часа, последние 200 на каждый ключ), поэтому вы можете найти точный запрос позже и повторить его из Активности прямо в Playground. Указывайте его при обращении в поддержку, это позволит найти запрос за считанные секунды.

$ 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

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

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

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

Для более подробного разбора выбора endpoint см. Choosing the Right Endpoint и руководство Smart Fetch guide.

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

Цели, которые разрешаются в частные, loopback или зарезервированные диапазоны IP (RFC 5735, RFC 6598, зарезервированные блоки IPv6), отклоняются с ошибкой 400 до того, как request покинет FourA. Пересылаются только публичные имена хостов и IP.

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

Умный запрос (Auto)

POST /api/auto/

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

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

Тело запроса

Параметр Тип Обязательно По умолчанию Описание
url string Да - Целевой URL
method string Нет "GET" Метод HTTP
headers [string, string][] Нет - Пользовательские заголовки в виде пар [name, value]
data any Нет - Тело запроса для запросов, отличных от GET
validate object Нет - Критерии успеха, структура совпадает с validate для Single Request (см. ниже). Укажите auto, как выглядит реальная страница, чтобы отличить контент от страницы проверки.
returnSession boolean Нет true Включить успешную сессию (proxy, cookies, userAgent) в ответ, чтобы вы могли воспроизвести ее через /api/single/ или /api/browser/.
forceProxy boolean Нет true Всегда направлять через ротационный proxy. Установите false для разрешения более дешевого прямого пути, когда цель это позволяет (некоторые защиты строже к трафику proxy).
timeout_ms integer Нет 120000 Общий бюджет времени для всего вызова в миллисекундах. Все подзапросы выполняются в рамках этого бюджета. Минимум 5000, максимум 180000.
ignoreProxies string[] Нет - ID proxy, которых следует избегать при каждой попытке. Используйте ID, возвращенные предыдущими ответами /api/auto/ или /api/proxy/.
followRedirects integer Нет 5 Максимальное количество перенаправлений для следования на дешевых уровнях. 0 для отключения. Максимум 20.

Ответ

{
  "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 or object Тело ответа.
headers array or object Заголовки ответа цели. Ступени single и proxy возвращают массив объектов заголовков для каждого перехода, ступени browser возвращают плоский объект.
meta.rung string Какая ступень (rung) доставила ответ. Одно из значений: probe (дешевый прямой запрос), proxy (ротируемый proxy), browser (полный рендеринг в браузере), cache (повтор прогретой сессии) или fail (ни одна ступень не дала принятого ответа).
meta.solved boolean Была ли решена проверка на бота во время этого вызова.
meta.attempts number Количество подпопыток до успеха.
meta.credits number Общее количество кредитов, потраченных на этот вызов. Совпадает с X-FourA-Credits.
session.proxy string Закодированный ID прокси, доставившего ответ. Используйте его повторно в запросах 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 в каждый подвызов. Каждый подвызов появляется в вашем Журнале активности; внешний вызов /api/auto/ не добавляет отдельную строку тарификации.
  • Передайте validate.data.accept с подстрокой, которую содержит только реальная страница. Без нее auto не сможет отличить реальный статус 200 от промежуточной страницы проверки (challenge), возвращаемой со статусом 200.
  • timeout_ms ограничивает по времени весь вызов. Первый холодный запрос к защищенному сайту может занять десятки секунд, повторно используемые теплые сессии обычно завершаются менее чем за секунду.

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][] Нет - Пользовательские заголовки в виде пар [имя, значение]
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 Нет отключено Максимальное количество перенаправлений (0-20). Опустите для отключения.
tryJsonData boolean Нет false Разбирать тело ответа как JSON, если возможно
returnBuffer boolean Нет false Возвращать сырой буфер вместо декодированной строки
data any Нет - Тело запроса (строка или объект, автоматически сериализуется в JSON)
proxy string Нет - Идентификатор proxy из предыдущего ответа для закрепления того же выходного узла. Передайте непрозрачную строку обратно без изменений. Прямой адрес proxy отклоняется с 400 Invalid proxy format.
browser string Нет Chrome Представляемый браузер: Chrome, Edge, Safari, Firefox или Tor. См. Профили браузеров.
os string Нет - Представляемая операционная система: Windows, macOS, Android или iOS. Имя семейства включает любую из его версий.
version string Нет newest Представляемая версия браузера, указанная в каталоге. При совпадении нескольких вариантов выбирается новейший.
profile string Нет - Точный идентификатор профиля из GET /api/profiles вместо трех полей выше.
validate object Нет - Правила валидации ответа (см. ниже)

Профили браузеров

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

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

Правила:

  • Для выбора требуется unblocker (включено по умолчанию). При выключенном разблокировщике header браузера не отправляются, поэтому request отклоняется, а не применяется частично.
  • Если совпадает несколько профилей, выбирается самая новая версия.
  • Комбинация, отсутствующая в каталоге, возвращает ошибку с указанием доступных вариантов. request никогда не отправляется под видом другого браузера.
  • Те же четыре поля доступны внутри объекта request в POST /proxy/.

GET /api/profiles возвращает полный каталог и не требует ключа API:

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

osFamily представляет собой значение для фильтрации при создании элемента выбора, а os хранит имя релиза для отображения.

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

Объект validate позволяет задавать условия успеха и ошибки. Если совпадает условие fail, запрос считается неудачным. Если заданы условия accept, успешными считаются только совпавшие ответы.

{
  "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 Пары ключ-значение для header, которые должны присутствовать
validate.headers.fail object Пары ключ-значение для header, которые вызывают ошибку
validate.data.accept string[] Строки, которые должны присутствовать в теле response
validate.data.fail string[] Строки в теле response, которые вызывают ошибку

Пример

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": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342,
  "proxy": "A1B2C3"
}

Если целевой ресурс выполняет проверку на ботов перед возвратом тела ответа, ответ также содержит объект 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 Присутствует только если целевой сервер запустил проверку на ботов для этого запроса. defense.solved указывает, была ли пройдена проверка. Смотрите Anti-Bot Defenses для всех полей и полного списка поставщиков.
error string Сообщение об ошибке, если запрос не удался

Proxy Request

POST /api/proxy/

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

Тело запроса

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

Ограничение 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"
    }
  }'

Ответ:

{
  "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.
total number Общая продолжительность в секундах (float). Включает выбор proxy, повторные попытки и успешную попытку. total_time представляет собой только внутренний request; total всегда >= total_time.
error string Сообщение об ошибке, если request завершился неудачно. При несовпадении области действия (scope), code имеет значение no_eligible_proxy, а details.exitCountries возвращает нормализованный scope.

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

Browser Request

POST /api/browser/

Открывает ваш URL в экземпляре браузера Chrome. Страница загружается, JavaScript выполняется, и вы получаете полностью отрендеренный HTML плюс хранилище cookie.

Тело request

Параметр Тип Обязательно По умолчанию Описание
url string Да - Целевой URL
headers object Нет - Пользовательские headers в виде пар ключ-значение
cookies array Нет - Устанавливаемые cookie: [{name, value, domain?}]
userAgent string Нет - Пользовательская строка User-Agent
unblocker boolean Нет true Автоматически решать распространенные проверки на ботов (Cloudflare clearance, аналогичные проверки) во время загрузки страницы. Включено по умолчанию. Задайте false, чтобы отобразить то, что возвращает страница, включая страницу проверки, без решения.
proxy string Нет - ID proxy из более раннего response для закрепления того же узла выхода. Передайте непрозрачную строку обратно без изменений. Сырой адрес proxy отклоняется с 400 Invalid proxy format.
timeout_ms number Нет 30000 Таймаут загрузки страницы в мс (макс: 120000)
checkStatus number Нет - Ожидаемый статус HTTP (request завершается неудачей, если отличается)
checkText string Нет - Текст, который должен появиться на отрендеренной странице

Пример

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

Ответ:

{
  "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 Заголовки ответа
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, если защита от ботов была встречена и успешно пройдена в этом вызове. В противном случае отсутствует. Определяет стоимость в 15 или 30 кредитов.
defenses object present содержит список всех вендоров, распознанных во время загрузки страницы, cleared содержит список тех, чье разрешение имеет финальная страница. Вендор может появиться в present и никогда не появиться в cleared. См. Защита от ботов.
proxy string Закодированный ID прокси, через который прошел запрос (только если proxy был указан в запросе). Используйте его повторно в последующих вызовах, чтобы сохранить тот же выходной узел.
error string Сообщение об ошибке, если запрос завершился неудачно

HTTP-коды состояния

Код Значение
200 Запрос завершен (проверьте внутренний status для ответа целевого ресурса)
400 Недопустимое тело запроса, параметры или целевой IP-адрес в приватном/зарезервированном диапазоне
401 Отсутствует или недействителен API-ключ
429 Превышен лимит запросов
500 Внутренняя ошибка сервера
502 Upstream unavailable. FourA связался с движком, но ответ оказался непригодным для использования. Повторите попытку.
503 Сервис временно отключен или перегружен, либо Backend service unavailable во время перезапуска движка
504 Upstream timeout. Движок не успел завершить работу в рамках бюджета времени для этого запроса. Увеличьте timeout_ms или повторите попытку.

Следующие шаги

Обновлено: 12 августа 2026 г.
Ошибки API →