# Smart Fetch (авто)

> URL: https://foura.ai/ru/docs/guides/smart-fetch
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

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

В этом руководстве объясняется, как auto работает под капотом, когда его использовать и как разбирать его response. Справочник по параметрам доступен в разделе [API Endpoints](https://foura.ai/docs/api/endpoints#smart-fetch-auto).

## Концепция

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

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

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

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

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

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

## Что отправлять в запросе

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

```bash
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](https://foura.ai/docs/api/endpoints#smart-fetch-auto)):

- `returnSession` (по умолчанию `true`): возвращает успешный `{ proxy, cookies, userAgent }` для повторного воспроизведения.
- `forceProxy` (по умолчанию `true`): пропускает уровни прямого egress. Устанавливайте `false`, только если сайт лучше принимает чистый IP, чем ротируемые exit-узлы.
- `timeout_ms` (по умолчанию `120000`): общий бюджет времени на весь вызов. Лестница распределяет его между уровнями.
- `ignoreProxies`: список ID proxy, которые следует исключать при каждой подпопытке.
- `followRedirects` (по умолчанию `5`): максимум перенаправлений на начальных недорогих уровнях.
- `headers`: заголовки для отправки на целевой сайт в виде пар `[name, value]`. Они передаются в запросах Single и Proxy, включая поиск рабочего exit-узла; браузерные уровни их не отправляют. Ваш собственный заголовок `Cookie` доходит до сайта без изменений, а cookie прогретой сессии добавляются рядом только под именами, которые вы не передавали. Если прогретая сессия содержит `userAgent`, он заменяет ваш `User-Agent`. Условные заголовки, такие как `If-None-Match` и `If-Modified-Since`, исключаются из поиска exit-узла, если в вашем `validate.status.accept` не указан `304`.
- `exitClass`: значение `premium` разрешает режиму Auto эскалацию до премиум exit-узла, если стандартный пул не может открыть страницу; `standard` запрещает любую эскалацию. Требуется тарифный план с поддержкой премиум exit-узлов. См. раздел [exitClass в Smart Fetch](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch).

## Что возвращается в ответе

```json
{
  "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` и `data`**: ответ целевого ресурса. `data` представляет собой текст независимо от того, какая ступень отдала страницу, поэтому страница JSON приходит как текст JSON, и вы парсите его самостоятельно. `status` это HTTP-статус целевого ресурса, а не транспортный статус вашего вызова к FourA. Для ступеней single и proxy `headers` является массивом по каждому хопу. Для ступеней browser `headers` представляет собой плоский объект.
- **`meta`**: трассировка действий лестницы, присутствующая в каждом ответе после запуска лестницы. `meta.rung` указывает шаг, доставивший ответ, `meta.attempts` считает попытки подвызовов, `meta.solved` сигнализирует, была ли пройдена страница проверки challenge, а `meta.credits` показывает общий расход на вызов (то же число, что и в заголовке `X-FourA-Credits`). `meta.attemptsByEngine` и `meta.browserRequests` показывают, что именно отправил вызов: смотрите [Сколько потратил вызов](#what-a-call-spent). Если в запросе был указан `exitClass`, то `meta.exitClass` указывает, какой класс выхода выполнил доставку.
- **`session`**: тройка `{ proxy, cookies, userAgent }`, открывшая целевой ресурс. Используйте ее для повторного вызова к тому же хосту через `/api/single/` или `/api/browser/`. Поле может отсутствовать: сессия, полученная обычным запросом через proxy, содержит `proxy`, но не содержит `userAgent`, а список `cookies` хранит только cookie, установленные проверочной страницей сайта до того, как сайт отдал страницу, поэтому он часто пуст. Ответ от дешевой прямой пробы содержит `session` только в том случае, если такая проверочная страница установила cookie, и тогда он содержит исключительно `cookies`. Статус, перечисленный в вашем `validate.status.accept` и возвращенный выходом (например, `404` для удаленной страницы), вообще не содержит `session`.

Auto отвечает с HTTP 200 всегда, когда запускалась лестница, даже если все ступени завершились ошибкой. Чтобы понять, что произошло, читайте `status` и `error` в теле ответа, а не код статуса транспорта. Ответ, отличный от 200, от `/api/auto/` означает, что вызов вообще не дошел до лестницы: 401 при неверном ключе, 400 для тела с некорректным JSON, при целевом ресурсе в частной сети, при целевом ресурсе на собственном API-хосте FourA или при наличии в URL незакодированного пробела, 403 с `X-FourA-Limit: plan_limit_premium` для `exitClass: premium` на тарифе без премиум-выходов, а также 502, 503 или 504, когда сервис не смог принять вызов или истекло время ожидания. Auto не занимает слот на шлюзе, поэтому общие лимиты платформы не отклоняют сам вызов: когда один из них отклоняет вызов, сделанный лестницей, возвращается ответ HTTP 200 с `status: 429` или `503` и `retryAfter` в теле. Поле, не прошедшее валидацию, также возвращается со статусом HTTP 200 и `status: 400`. Достижение лимита тарифного плана внутри лестницы также возвращается со статусом HTTP 200 с отказом в теле ответа (смотрите [Когда лимиты вашего тарифа сталкиваются с лестницей](#when-your-plans-limits-meet-the-ladder)).

## Повторные запросы с сессией

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

```python
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.get("session") or {}
proxy = session.get("proxy")
user_agent = session.get("userAgent")

# 2) Follow-up pages: replay through single with the same proxy, UA and cookies.
for sku in ("43", "44", "45"):
    body = {"method": "GET", "url": f"https://example.com/product/{sku}"}
    if proxy:
        body["proxy"] = proxy
    headers = []
    if user_agent:
        headers.append(["User-Agent", user_agent])
    if session.get("cookies"):
        headers.append(["Cookie", "; ".join(f"{c['name']}={c['value']}" for c in session["cookies"])])
    if headers:
        body["headers"] = headers
    r = requests.post(f"{API}/api/single/", headers=H, json=body).json()
    print(sku, r["status"])
```

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

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

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

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

## Validate определяет для Auto критерий успешного ответа

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

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

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

Для JSON API укажите ожидаемое имя поля:

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

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

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

Auto возвращает статус, указанный вами в `validate.status.accept`, как только точка выхода возвращает его и он проходит остальную часть вашего правила. Четыре статуса являются исключением: `202`, `403`, `429` и `503`. Auto расценивает их как проверку отправителя со стороны сайта, поэтому возврат одного из них не завершает поиск, и лестница продолжает подниматься.

Без `validate` режим auto возвращается к логике "HTTP 200 = успех" для любой страницы, которую он не распознал как проверку, поэтому он не перехватит незнакомую страницу проверки, возвращаемую сайтом с кодом 200.

## Анализ `meta.rung` для понимания происходящего

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

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

`meta.solved: true` означает, что во время вызова была обнаружена и пройдена страница проверки. `meta.attempts` указывает количество попыток подзапросов до успешного завершения. Подробные сведения см. в поле `defense`, возвращаемом ступенями single и proxy: смотрите [Проверки сайтов](https://foura.ai/docs/api/site-checks).

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

## Расход ресурсов на вызов

`meta.attemptsByEngine` подсчитывает количество запросов, отправленных вызовом на каждый движок; это те же запросы, которые панель Auto attempts отображает на вашей странице [Overview](https://foura.ai/docs/dashboard/overview). `meta.browserRequests` подсчитывает те из них, которые израсходовали лимит вашего ежедневного браузерного пакета.

```json
"meta": {
  "rung": "browser",
  "solved": true,
  "attempts": 7,
  "credits": 47,
  "attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
  "browserRequests": 2
}
```

| Поле | Тип | Описание |
|-------|------|-------------|
| `meta.attemptsByEngine` | object | Запросы, отправленные в `single`, `proxy` и `browser`. Браузерный request, отклоненный вашим тарифом, учитывается здесь, так как он был отправлен. |
| `meta.browserRequests` | number | Браузерные запросы, использовавшие слот из вашего дневного лимита. Браузерный request, отклоненный вашим тарифом, ничего не расходует. |

`meta.attempts` считает шаги цепочки, поэтому значение не всегда равно сумме `meta.attemptsByEngine`. Один шаг может отправить Single request, а затем Proxy request, а шаг, чей браузер уже отключен на сегодня, не отправляет ничего.

Текущий счетчик за день передается в headers `X-FourA-Browser-Used-Today` и `X-FourA-Browser-Limit-Per-Day`: см. [Response Headers](https://foura.ai/docs/api/response-headers).

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

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

```json
{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "attemptReport": {
    "total": 7,
    "noResponse": 5,
    "defense": 2,
    "contentRejected": 0,
    "statusRejected": 0,
    "other": 0,
    "vendors": ["datadome"],
    "summary": "7 attempt(s): 5 got no answer from the site; 2 refused by the site (datadome)"
  },
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47,
    "attemptsByEngine": {"single": 0, "proxy": 4, "browser": 3},
    "browserRequests": 3
  }
}
```

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

Auto также останавливается раньше времени, когда его браузер постоянно сталкивается с проверкой, которую не может пройти. После того как два выходных узла отклоняют браузер таким образом, а поиск узла, чей прямой запрос удовлетворяет вашему правилу `validate`, не дает результатов, либо после трех таких узлов вызов завершается. `status` содержит последний ответ сайта, а `error` начинается с `the browser was refused by`, за которым следует название системы проверки.

Auto также останавливается, когда сам сайт сообщает, что страница отсутствует. Когда два выходных узла возвращают один и тот же `404` или `410`, а ваши правила не принимают его, вызов завершается с этим `status`, а `error` начинается с `the site answered`. Если удаленная страница является ожидаемым ответом, укажите `404` или `410` в `validate.status.accept`: тогда Auto вернет ее как доставленную, как только узел вернет этот результат.

После того как четыре вызова Auto подряд с вашим API-ключом завершаются без получения страницы из-за постоянных отказов сайта, Auto перестает обращаться к этому сайту для вашего ключа на 120 секунд. Запрос к нему в течение этого времени мгновенно возвращает ответ с `status: 503`, `error: "target temporarily unservable, retry later"` и `retryAfter` в секундах, и ничего не стоит. Учет ведется по API-ключу: другие ключи, обращающиеся к тому же сайту, не затрагиваются, а любой успешный вызов, получивший страницу, сбрасывает счетчик. Вызов с `exitClass: premium` этой блокировкой не останавливается.

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

### Причины сбоя вызова Auto

Каждый неудачный ответ от выполненной лестницы содержит `attemptReport`. Он однократно подсчитывает запросы движка, вернувшиеся без страницы, классифицируя их по возникшей проблеме.

| Поле | Тип | Описание |
|-------|------|-------------|
| `total` | integer | Запросы, вернувшиеся без страницы. Не более суммы `meta.attemptsByEngine`, так как отклоненный вашим тарифом запрос браузера даже не обращался к цели. |
| `noResponse` | integer | Сайт не ответил |
| `defense` | integer | Сайт отклонил запрос: обнаружена проверка на ботов, получена страница проверки (challenge) или сайт ответил со статусом 401, 403, 429 либо 503 |
| `contentRejected` | integer | Страница была получена, и только ваше правило `validate` отклонило ее |
| `statusRejected` | integer | Сайт ответил со статусом, который не принимает ваш запрос, например 404 для удаленной страницы |
| `other` | integer | Ошибка по другой причине, например сбой сервера |
| `vendors` | string[] | Поставщики защиты от ботов, распознанные при отказах, с которыми столкнулся вызов |
| `summary` | string | Одно предложение, сформированное на основе счетчиков, безопасное для логирования. В нем указывается статус HTTP, с которым ответил сайт, если поставщик не был распознан, а также сообщается об исчерпании дневного лимита браузера, из-за чего браузер не мог быть запущен. |

Поля соответствуют отчету о неудачном [вызове Proxy](https://foura.ai/docs/troubleshooting/proxy-attempt-report), без `profilesTried`. Есть два отличия. Proxy считает каждую опробованную точку выхода в пределах заданного вами `maxTries`, а Auto считает свои собственные запросы. Auto также анализирует страницу и ее статус, поэтому отказ учитывается в `defense`, даже если поставщик защиты не был распознан. Счетчик `contentRejected` относится к случаям, которые вы можете исправить сами: страница вернулась, но ваше правило не совпало.

### Когда лимиты вашего тарифа влияют на цепочку попыток

Вложенные вызовы Auto представляют собой обычные запросы Single, Proxy и Browser с использованием вашего ключа, поэтому на них распространяются [лимиты вашего тарифа](https://foura.ai/docs/api/rate-limits). Цепочка считывает код `X-FourA-Limit` при отказе и обрабатывает два типа ситуаций по-разному.

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

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

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

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

Один вызов auto может занимать несколько слотов во время прохождения цепочки, поэтому параллельный пакет вызовов auto достигает предела параллелизма при меньшем количестве вызовов, чем ожидается. В разделе [Запуск параллельных запросов](https://foura.ai/docs/how-to/run-requests-in-parallel) описан выбор размера пакета.

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

- Не отменяет юридические ограничения. Если сайт отклоняет все доступные FourA точки выхода, auto возвращает этот отказ.
- Не кэширует контент. Каждый вызов по-прежнему обращается к цели. "Прогретая сессия" включает proxy и cookies, но не сам response.
- Отображается как одна строка в [Activity Log](https://foura.ai/docs/dashboard/activity-log) под полученным вами request id, с суммой кредитов его подвызовов. Откройте ее, и подвызовы Single / Proxy / Browser, выполненные auto от вашего имени, будут перечислены как попытки со своим собственным результатом. Они учитываются в лимитах Single, Proxy и Browser, но не влияют на общее число запросов или success rate.

## См. также

- [API Endpoints](https://foura.ai/docs/api/endpoints#smart-fetch-auto): Полный справочник параметров
- [Выбор подходящего endpoint](https://foura.ai/docs/guides/choosing-task-type): Когда выбирать auto, а когда single, proxy или browser
- [Результаты запросов](https://foura.ai/docs/api/outcomes): Какие результаты тарифицируются
- [Защищенные сайты](https://foura.ai/docs/guides/protected-sites): Поведение FourA на сайтах с проверкой клиентов
- [Проверки сайта](https://foura.ai/docs/api/site-checks): Поле `defense` за пределами `meta.solved`
- [Сценарии MCP](https://foura.ai/docs/mcp/recipes): Те же шаблоны в виде вызовов инструментов MCP
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Лимиты тарифа, по которым оцениваются подвызовы auto
