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

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

В этом руководстве описано, как работает auto под капотом, когда его использовать и как читать ответ. Справочник по параметрам доступен в разделе API Endpoints.

Концепция

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

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

Дешевый probe-запрос (single, напрямую из собственной сети FourA)
Browser, напрямую из собственной сети FourA, с JavaScript и решением проверок, если сайт выдает challenge
Single через ротируемый proxy
Browser через proxy для самых сложных целей

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

Одна ступень находится вне этого порядка. Если точка выхода подключается к сайту, но сайт отклоняет запрошенный глубокий URL, auto запрашивает главную страницу сайта через ту же точку выхода, сохраняет выданные ею cookie и повторяет запрос к вашему URL вместе с ними. Это ступень warmup. Она запускается только для URL глубже корня сайта, только после неудачи прямого запроса и может только добавить положительный результат, но не отменить его.

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

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

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

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

Режим Auto возвращает HTTP 200 во всех случаях, когда цепочка ladder выполнилась, даже если каждый уровень завершился с ошибкой. Чтобы понять результат, проверяйте status и error в теле ответа, а не транспортный код статуса. Код ответа, отличный от 200 от /api/auto/, означает, что вызов не дошел до ladder: 401 при неверном ключе, 400 при невалидном JSON в теле запроса или целевом ресурсе в приватной сети, а 502, 503 или 504 возникают, если сервис не смог принять вызов или истекло время ожидания. Auto не занимает слот на шлюзе, поэтому общие лимиты платформы не отклоняют сам вызов: если лимит блокирует вызов, сделанный ladder, ответом будет HTTP 200 с status: 429 или 503 и retryAfter в теле. Ошибка валидации поля также возвращается как HTTP 200 с status: 400. Превышение лимита тарифного плана внутри ladder также возвращает HTTP 200 с описанием отказа в теле ответа (см. Когда лимиты вашего тарифа пересекаются с ladder).

Replaying with the Session

После того как auto вернет session, вы можете сразу переходить к 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"])

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

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

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

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

Параметр Validate определяет для Auto критерий успеха

Самый важный параметр это validate. Без него auto отклоняет только знакомые страницы проверок, поэтому неизвестная страница проверки или пустая заглушка с кодом HTTP 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 = успех" для любой страницы, которую он не распознал как проверку, поэтому он пропустит незнакомую страницу проверки, возвращенную сайтом с кодом 200.

Чтение `meta.rung` для анализа результатов

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

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

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

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

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

Когда auto завершается с ошибкой, response содержит status (обычно статус последнего неудавшегося уровня) и строку error:

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status содержит ответ сайта на последней попытке, которую отклонил auto, например 403. Если ни одна из попыток вообще не получила ответ от сайта, обычно возвращается 502 или 504, а error указывает, не был ли найден рабочий выходной узел или исчерпан бюджет timeout_ms. status: 0 означает только то, что имя хоста цели не удалось разрешить, и в этом ответе нет meta, так как ladder даже не запустился.

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

Когда лимиты вашего тарифа влияют на Ladder

Вложенные вызовы Auto представляют собой обычные запросы Single, Proxy и Browser под вашим ключом, поэтому на них распространяются лимиты вашего тарифа. Ladder считывает код X-FourA-Limit при отказе и обрабатывает два типа ситуаций по-разному.

Отключенная ступень оставляет остальную часть ladder доступной. plan_limit_browser_daily (исчерпан дневной лимит запросов Browser) и plan_limit_concurrency (на данном endpoint уже выполняется максимально допустимое тарифом количество ваших запросов) закрывают одну ступень. Auto продолжает использовать другие ступени, поэтому вы по-прежнему получаете страницу, если ротируемый выходной узел или прогретая сессия отдают контент, а проверенные выходные узлы не считаются сбойными из-за отказа со стороны лимитов вашего тарифа. Ничего не блокируется, и ни одна сессия не сбрасывается.

Исчерпание ресурсов аккаунта останавливает ladder. При ошибках plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature и plan_limit_premium переход на другую ступень не поможет, поэтому auto завершает работу сразу, не тратя ваши кредиты на заведомо безуспешные попытки. Отказ возвращается в теле ответа со статусом вложенного вызова и тем же полем reason, которое используют прямые endpoint:

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

Тело отказа из подзапроса передается полностью, плюс status и meta. Считывайте status из тела ответа, а не из транспортного статуса: auto здесь все равно возвращает HTTP 200, так как цепочка была выполнена. Отказ plan_limit_feature или plan_limit_premium приходит аналогично с status: 403. Отклоненный подзапрос не расходует средства, поэтому meta.credits учитывает только те шаги, которые дошли до целевого ресурса.

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

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

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

Связанные разделы

API Endpoints: полный справочник параметров
Выбор подходящего endpoint: когда использовать auto вместо single, proxy или browser
Результаты запросов: какие результаты тарифицируются
Защищенные сайты: поведение FourA на сайтах с проверкой источника
Проверки сайтов: поле defense для meta.solved
Сценарии MCP: аналогичные шаблоны в виде вызовов инструментов MCP
Rate Limits: лимиты тарифа, по которым оцениваются подзапросы auto

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