Умное извлечение (Auto)

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

Это руководство объясняет, что делает auto под капотом, когда его использовать и как читать его response. Для справочника по параметрам см. API Endpoints.

Идея

Большинство систем скрейпинга заставляют вас выбирать движок заранее. Single является самым быстрым, Proxy добавляет ротацию, Browser обрабатывает JavaScript. Вы ошибаетесь с выбором, вы тратите кредиты или получаете блокировку.

Auto меняет это. Вы объявляете успех (validate), а не метод. FourA поднимается по лестнице, пока одна из ступеней не сработает:

Cheap probe (single, прямо из собственной сети FourA)
Rotated proxy single
Browser, с JavaScript и решателем, если сайт выдает проверку
Browser through proxy для самых сложных целей

Auto останавливается, как только ступень возвращает response, который принимает ваше правило validate.

forceProxy по умолчанию равен true, поэтому ступень 1 пропускается, и цель никогда не видит собственный адрес FourA. Затем большинство вызовов завершается на ступени 2 или на повторно используемой прогретой сессии. Установите forceProxy: false, когда вы знаете, что цель относится к чистому адресу лучше, чем к ротируемому, и ступень 1 возвращается.

Что вы отправляете

Минимум это URL плюс подстрока validate. Без validate.data.accept auto не может отличить реальную страницу от промежуточной страницы проверки, возвращенной с HTTP 200, и может вернуть проверку как успех.

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

Дополнительные параметры (полную информацию см. в справочнике по endpoint):

returnSession (по умолчанию true): возвращает успешный { proxy, cookies, userAgent }, чтобы вы могли его повторить.
forceProxy (по умолчанию true): пропускает ступени direct-egress. Устанавливайте false, только если знаете, что сайт более лоялен к чистому IP, чем к бесплатным ротируемым proxy.
timeout_ms (по умолчанию 120000): общий бюджет для всего вызова. Лестница распределяет его между ступенями.
ignoreProxies: ID proxy, которых следует избегать при каждой подпопытке.
followRedirects (по умолчанию 5): максимальное количество редиректов на дешевых ступенях.

Что вы получаете в ответ

{
  "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 и data: та же структура, которую вернул базовый движок. status это HTTP статус цели, а не транспортный статус вашего вызова к FourA. Для ступеней single и proxy headers это массив по каждому узлу. Для ступеней browser headers это плоский объект.
meta: трассировка действий ladder, присутствует в каждом ответе. meta.rung указывает шаг, доставивший ответ, meta.attempts считает попытки подвызовов, meta.solved указывает, была ли пройдена проверка на бота, а meta.credits это общая стоимость вызова (то же число, что и в заголовке X-FourA-Credits).
session: тройка параметров { proxy, cookies, userAgent }, которая взломала цель. Используйте ее для повторного выполнения к тому же хосту через /api/single/ или /api/browser/.

Auto отвечает с HTTP 200 каждый раз, когда выполнялся ladder, даже если все ступени завершились ошибкой. Читайте status и error в теле, чтобы узнать, что произошло, а не транспортный код статуса. Ответ, отличный от 200 из /api/auto/, означает, что FourA отклонил вызов до запуска ladder: 401 для неверного ключа, 400 для неверного тела или приватной цели, 429 или 503 для rate limit.

Повтор с использованием сессии

После того как auto возвращает сессию, вы можете сразу перейти к Single или Browser для последующих страниц на том же хосте. Никакого нового прохождения ladder, никаких новых проверок.

import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

Сессия долговечна ровно настолько, насколько это позволяет целевой сайт. Некоторые сайты привязывают допуск к cookie на несколько часов, другие меняют его каждые несколько минут. Если повторный запрос снова начинает возвращать проверки (challenges), вызовите /api/auto/ еще раз для обновления.

Когда использовать Auto

Использовать auto	Использовать single, proxy или browser вручную
Вы обращаетесь к новому сайту и не знаете, что ему нужно	Вы уже знаете, какой движок работает
Вам нужен один вызов, который сам обрабатывает direct, proxy и резервный browser	Вам нужен полный контроль над повторами и таймаутами каждого вызова
Вас устраивает пара секунд на проверку при первом вызове	Задержка первого вызова важнее автоматического определения
Вы хотите получить готовую сессию, которую можно дешево повторять	Вы оптимизируете жесткий цикл для заведомо рабочей цели

Auto не всегда является самым дешевым вариантом. Если вы знаете, что цель работает с single + unblocker, прямой вызов Single обойдется в 2 кредита с предсказуемой задержкой. Использование Auto для той же цели будет стоить столько, сколько потратит его цепочка проверок, что может быть больше, если сайт требует повышения уровня.

Validate указывает Auto, что означает "успех"

Самый важный параметр это validate. Без него auto не сможет отличить настоящую страницу 200 от страницы проверки 200, замаскированной под контент.

Используйте validate.data.accept с подстрокой, которую содержит только настоящая страница:

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

Для JSON API принимайте ожидаемое имя поля:

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

Для сайтов, которые легитимно возвращают статус не 200 (геоблокировки, которые нужно игнорировать, намеренные ошибки 403 на неавторизованных endpoint), разрешите их через validate.status.accept:

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

Без validate auto откатывается к "HTTP 200 = success" и не перехватит промежуточную страницу проверки Cloudflare, которую WAF возвращает со статусом 200.

Чтение `meta.rung` для понимания произошедшего

meta.rung является самым полезным сигналом для отладки. Значения:

probe: решено с помощью дешевого прямого запроса. Самый дешевый путь.
proxy: потребовалась ротация proxy для прохождения.
browser: потребовался полный рендеринг в браузере, возможно, с решением проверки.
cache: повторно использована прогретая сессия от предыдущего вызова auto. Самый дешевый путь при повторных вызовах.
fail: ни один уровень не выдал ответ, который приняли бы ваши правила.

meta.solved: true означает, что проверка на бота была обнаружена и пройдена во время вызова. meta.attempts это количество попыток подвызовов до достижения успеха. Для получения подробной информации о поставщике, стоящем за решением, прочитайте поле defense, которое возвращают уровни single и proxy: см. Защита от ботов.

Если сайт постоянно завершается на browser, когда вы ожидали probe, подумайте, не позволит ли более строгое (или менее строгое) правило validate пройти более дешевому уровню. Помните, что forceProxy по умолчанию имеет значение true, поэтому проверка direct-egress пропускается, если вы ее не отключите.

Ошибки и крайние случаи

При сбое auto в ответе передается status (обычно статус последнего неуспешного уровня) и строка error:

{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status: 0 означает, что ни один уровень не дал ответа (все попытки завершились по тайм-ауту или были отклонены). Ненулевое значение status плюс error означает, что последняя попытка получила ответ, но auto отклонил его (validate или иначе).

Проверьте meta.attempts и meta.credits, чтобы узнать, куда ушел бюджет. Если meta.attempts высок, а meta.rung равен fail после уровня browser, целевому ресурсу может потребоваться больший timeout_ms, более строгое правило validate, или же он просто недоступен через ротационные proxy в данный момент.

Чего Auto не делает

Он не обходит правовые ограничения. Если сайт заблокирован по геопозиции и отклоняет каждый выходной узел, до которого может добраться FourA, auto возвращает блокировку.
Он не кэширует контент. Каждый вызов все равно достигает цели. "Прогретая сессия" означает proxy и cookies, а не response.
Он не пишет в Activity Log отдельной строкой от подвызовов. Подвызовы Single / Proxy / Browser, которые auto делает от вашего имени, появляются в Activity; внешний вызов /api/auto/ является координатором.

По теме

API Endpoints: Полный справочник параметров
Choosing the Right Endpoint: Когда выбирать auto, а не single, proxy или browser
Request Outcomes: Какие результаты подлежат оплате
Anti-Bot Protection: Что делает FourA с Cloudflare, DataDome и подобными системами
Anti-Bot Defenses: Поле defense, скрытое за meta.solved
MCP Recipes: Те же паттерны, что и при вызовах инструментов MCP

Обновлено: 12 августа 2026 г.