Docs › Ръководства › Интелигентно извличане (Auto)

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

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

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

Идеята

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

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

  1. Евтина проверка (single, директно от собствената мрежа на FourA)
  2. Browser, директно от собствената мрежа на FourA, с JavaScript и механизъм за решаване при възникване на защита от сайта
  3. Single през ротиращо proxy
  4. Browser през proxy за най-трудните цели

Auto спира веднага щом дадено стъпало върне response, който вашето правило validate приема.

Едно стъпало стои извън този ред. Когато даден изходен възел достигне до сайта, но сайтът откаже достъп до заявения от вас вътрешен URL, auto извлича началната страница на сайта през същия изходен възел, запазва бисквитките (cookies), върнати от началната страница, и прави нова заявка за вашия 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 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: отговорът на таргета. data е текст на всяко стъпало: JSON страница се връща като JSON string дори когато е обслужена от браузър, така че я парснете от ваша страна. status е HTTP статусът на таргета, а не транспортният статус на вашето повикване към FourA. За единични и proxy стъпала, headers е масив за всеки hop. За браузърни стъпала, headers е плосък обект.
  • meta: следата на извършеното от стълбицата, налична при всеки response след стартиране на стълбицата. meta.rung посочва стъпката, доставила отговора, meta.attempts брои опитите за подповиквания, meta.solved отбелязва дали страница с предизвикателство е била завършена, а meta.credits е общият разход за повикването (същото число като в хедъра X-FourA-Credits).
  • session: тройката { proxy, cookies, userAgent }, която е пробила таргета. Използвайте я за повторно изпълнение срещу същия host чрез /api/single/ или /api/browser/.

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

Повторно изпълнение със Session

След като auto върне сесия, можете директно да преминете към Single или Browser за последващи страници на същия host. Без ново изкачване по стълбицата, без ново сондиране.

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

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

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

Auto не винаги е най-евтиният избор. Ако знаете, че целта работи с single + unblocker, директното извикване на Single струва 2 кредита с предвидимо latency. Auto за същата цел струва толкова, колкото изразходва стълбицата му, което може да бъде повече, ако сайтът изисква ескалация.

Validate показва на Auto какво означава "Success"

Единственият най-важен параметър е 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 при излезли от профила endpoints), ги разрешете чрез validate.status.accept:

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

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

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

meta.rung е най-полезният сигнал за дебъгване. Стойности:

  • probe - решено чрез евтин direct request. Най-евтиният път.
  • proxy - изискваше ротация на proxy, за да премине.
  • browser - изискваше пълен render в браузър, възможно с решаване на challenge.
  • cache - преизползва топла сесия от предишно auto извикване. Най-евтиният път при повторни извиквания.
  • warmup - сайтът предостави началната си страница, но ограничи достъпа до вътрешния URL, така че auto първо изтегли началната страница, запази върнатите cookies и направи нова заявка с тях. Сесията, която се запазва от това ниво, не е обвързана с единичен изход, така че следващите извиквания попадат на евтините нива.
  • fail - нито едно ниво не върна response, приет от вашите правила.

meta.solved: true означава, че по време на извикването е засечена и завършена challenge страница. 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, тъй като стълбицата въобще не е стартирала.

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

Когато лимитите на плана ви срещнат стълбицата

Вътрешните повиквания на auto са обикновени Single, Proxy и Browser заявки с вашия ключ, така че лимитите на плана ви се прилагат и за тях. Стълбицата прочита кода 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, което използват директните endpoints:

{
  "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 повиквания достига тавана за едновременност с по-малко заявки, отколкото бихте очаквали. Run Requests in Parallel покрива оразмеряването на пакета.

Какво Auto не прави

  • Не променя правните ограничения. Ако даден сайт откаже всяка изходна точка, до която FourA има достъп, auto връща този отказ.
  • Не кешира съдържание. Всяко повикване достига директно до целта. "Warm session" представлява проксито и бисквитките, а не върнатият отговор.
  • Записва се като един ред в Activity Log, под request id, което сте получили, със сбора от кредитите на неговите подповиквания. Отворете го и Single / Proxy / Browser подповикванията, направени от auto от ваше име, са изброени като негови опити, всеки със собствен резултат. Те се отчитат към вашите Single, Proxy и Browser лимити, никога към броя заявки или процента на успеваемост.

Свързани теми

  • API Endpoints: Пълна документация на параметрите
  • Choosing the Right Endpoint: Кога да изберете auto спрямо single, proxy или browser
  • Request Outcomes: Кои резултати са платими
  • Protected sites: Какво прави FourA при сайтове, проверяващи кой прави заявката
  • Site checks: Полето defense зад meta.solved
  • MCP Recipes: Същите модели като MCP tool calls
  • Rate Limits: Лимитите на плана, спрямо които се измерват подповикванията на auto
Обновено: 30 септември 2026 г.
← Как се отчита вашият план