Интелигентно извличане (Auto)

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

Това ръководство обяснява какво прави auto под капака, кога да го използвате и как да четете неговия response. За справка на параметрите вижте API Endpoints.

Идеята

Повечето конфигурации за извличане (scraping) ви карат да изберете engine предварително. Single е най-бърз, Proxy добавя ротация, Browser се справя с JavaScript. Ако не познаете, губите кредити или бивате блокирани.

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

Евтина сонда (single, директно от собствената мрежа на FourA)
Ротиран proxy single
Browser, с JavaScript и solver, ако сайтът изисква проверки
Browser през 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): пропуска нивата за директен изход. Задайте false само ако знаете, че сайтът е по-благоприятно настроен към чист IP адрес, отколкото към безплатни ротиращи proxy сървъри.
timeout_ms (по подразбиране 120000): общ бюджет за цялото извикване. Стълбата го разпределя между нивата.
ignoreProxies: proxy ID-та, които да се избягват при всеки под-опит.
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: същата структура, върната от основния engine. status е HTTP статусът на целта, а не транспортният статус на вашето извикване към FourA. За single и proxy стъпки, headers е масив за всеки скок. За browser стъпки, headers е плосък обект.
meta: проследяването на това, което ladder направи, присъстващо във всеки response. meta.rung посочва стъпката, която достави response, meta.attempts отчита опитите за подизвиквания, meta.solved отбелязва дали е преминато bot challenge, а meta.credits е общият разход за извикването (същото число като X-FourA-Credits header).
session: тройката { proxy, cookies, userAgent }, която разби целта. Използвайте я за повторно пускане срещу същия хост чрез /api/single/ или /api/browser/.

Auto отговаря с HTTP 200, когато ladder се изпълни, дори когато всяка стъпка е неуспешна. Прочетете status и error в тялото, за да разберете какво се е случило, а не кода на транспортния статус. Различен от 200 код от /api/auto/ означава, че FourA е отхвърлил извикването преди стартирането на ladder: 401 за невалиден ключ, 400 за невалидно тяло или частна цел, 429 или 503 за rate limits.

Повторно пускане със сесията

След като 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 хранилището за часове, други го сменят на всеки няколко минути. Ако повторното изпълнение започне отново да връща предизвикателства, извикайте /api/auto/ още веднъж, за да обновите.

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

Използвайте auto	Използвайте ръчно single, proxy или browser
Насочвате се към нов сайт и не знаете какво изисква той	Вече знаете кой engine работи
Искате едно извикване, което обработва direct, proxy и browser fallback вместо вас	Искате пълен контрол върху повторните опити и времевите ограничения за всяко извикване
Съгласни сте да отделите няколко секунди за тестване при първото извикване	Латентността на първото извикване е по-важна от откриването
Искате научена сесия, която можете да повтаряте евтино	Оптимизирате тесен цикъл върху добре позната цел

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 на endpoints без логване), разрешете ги чрез validate.status.accept:

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

Без validate, auto преминава към "HTTP 200 = success" и няма да хване Cloudflare challenge interstitial, който WAF връща с 200.

Четене на `meta.rung` за разбиране на случилото се

meta.rung е най-полезният debug сигнал. Стойности:

probe - решен с евтин директен request. Най-евтиният път.
proxy - изисква proxy ротация за преминаване.
browser - изисква пълно рендиране в браузър, евентуално с решаване на challenge.
cache - възпроизвежда активна сесия от предишно auto извикване. Най-евтиният път при повторни извиквания.
fail - нито една стъпка не генерира response, приет от вашите правила.

meta.solved: true означава, че bot challenge е открит и преминат по време на извикването. meta.attempts е броят на опитите за подизвиквания преди успех. За подробности относно доставчика зад решението, прочетете полето defense, което single и proxy стъпките връщат: вижте Anti-Bot Defenses.

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

Грешки и гранични случаи

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

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

status: 0 означава, че нито едно ниво не е генерирало response (всеки опит е изтекъл или е бил отхвърлен). Ненулев status плюс error означава, че последният опит е получил response, но auto го е отхвърлил (чрез validate или по друг начин).

Проверете meta.attempts и meta.credits, за да видите къде е изразходван бюджетът. Ако meta.attempts е високо и meta.rung е fail след нивото на браузъра, целта може да се нуждае от по-дълъг timeout_ms, по-строго правило за validate или просто не е достъпна чрез ротиращи proxies в момента.

Какво 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 tool calls

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