Smart Fetch (Автоматично)
Подавате на FourA даден URL и правило validate за това какво трябва да съдържа същинската страница. FourA прави останалото: преминава през стълбица, съобразена с разходите, спира на първото стъпало, което върне response, приет от вашите правила, и запомня кое е сработило за съответния host, така че следващото извикване към същия сайт да бъде евтино.
Това ръководство обяснява какво прави auto под капака, кога да го използвате и как да четете неговия response. За справка относно параметрите вижте API Endpoints.
Идеята
Повечето конфигурации за scraping ви карат да изберете engine предварително. Single е най-бърз, Proxy добавя ротация, Browser обработва JavaScript. Ако сбъркате в преценката, губите кредити или бивате блокирани.
Auto обръща този подход. Вие дефинирате успех (validate), а не метод. FourA изкачва стълбица, докато някое стъпало не успее:
- Евтина сонда (single, директно от собствената мрежа на FourA)
- Browser, директно от собствената мрежа на FourA, с JavaScript и solver, ако сайтът постави предизвикателство
- Single с ротирано proxy
- Browser през proxy за най-трудните цели
Auto спира веднага щом някое стъпало върне response, който вашето правило validate приема.
Едно стъпало стои извън този ред. Когато даден exit достигне сайта, но сайтът откаже дълбокия URL, който сте поискали, auto извлича входната страница на сайта през същия този exit, запазва бисквитките (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 reference за пълни подробности):
returnSession(по подразбиранеtrue): връща печелившата{ proxy, cookies, userAgent }, за да можете да я повторите.forceProxy(по подразбиранеtrue): пропуска стъпките с директен изход (direct-egress). Задайтеfalseсамо ако знаете, че сайтът приема по-добре чист IP адрес, отколкото ротиращи изходи.timeout_ms(по подразбиране120000): общ бюджет за цялото извикване. Стълбицата го разпределя между отделните стъпки.ignoreProxies: proxy ID-та, които да се избягват при всеки подизпълнителен опит.followRedirects(по подразбиране5): максимален брой пренасочвания при евтините стъпки.headers: headers за изпращане към сайта като двойки[name, value]. Те се изпращат при Single и Proxy заявките, включително при търсенето на работещ изход, като стъпките с браузър не ги изпращат. Вашият собственCookieдостига до сайта непроменен, а бисквитките от активна сесия се добавят към него само с имена, които не сте изпратили. Когато активната сесия съдържаuserAgent, той заменя вашияUser-Agent. Условни headers катоIf-None-MatchиIf-Modified-Sinceсе пропускат при търсенето на изход, освен ако вашиятvalidate.status.acceptне съдържа304.exitClass:premiumпозволява на Auto да ескалира до premium изход, след като стандартният пул не успее да достигне страницата;standardопределя никога да не се ескалира. Изисква план, който включва premium изходи. Вижте exitClass on Smart Fetch.
Какво получавате в отговор
{
"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 и proxyheadersе масив за всеки хоп. За стъпалата с браузърheadersе плосък обект.meta: трасировката на извършеното от стълбицата, налична във всеки response след стартиране на стълбицата.meta.rungпосочва стъпката, доставила отговора,meta.attemptsброи опитите за подизвиквания,meta.solvedуказва дали е премината страница с предизвикателство, аmeta.creditsе общият разход за извикването (същото число като в хедъраX-FourA-Credits).meta.attemptsByEngineиmeta.browserRequestsпоказват какво е изпратило извикването: вижте Какво изразходва едно извикване. Когато заявката посочваexitClass,meta.exitClassуказва кой клас изход е доставил резултата.session: тройката{ proxy, cookies, userAgent }, с която е преодоляна защитата на целта. Използвайте я за повторно изпълнение към същия хост чрез/api/single/или/api/browser/. Дадено поле може да липсва: сесия, спечелена чрез обикновено proxy извличане, съдържаproxy, но не иuserAgent, а нейният списъкcookiesсъдържа само бисквитките, зададени от страница за проверка на сайта преди зареждане на страницата, така че често е празен. Отговор от евтината директна сонда съдържаsessionсамо когато такава страница за проверка е задала бисквитки, и тогава съдържа единствено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, с отхвърлянето в тялото (вижте Когато лимитите на вашия план срещнат стълбицата).
Повторно изпълнение със сесията
След като auto върне сесия, можете да преминете директно към Single или Browser за последващи страници на същия хост. Без ново катерене по стълбицата, без нова сонда.
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 започне отново да връща challenges, извикайте /api/auto/ още веднъж за обновяване.
Кога да използвате Auto
| Използвайте auto | Използвайте single, proxy или browser ръчно |
|---|---|
| Насочвате се към нов сайт и не знаете от какво се нуждае | Вече знаете кой engine работи |
| Искате едно извикване, което управлява proxy и browser fallback вместо вас | Искате пълен контрол върху retries и timeouts за всяко извикване |
| Готови сте да изчакате няколко секунди за probing при първото извикване | Latency при първото извикване е по-важно от откриването |
| Искате научена сесия, която можете да преигравате евтино | Оптимизирате стегнат цикъл върху предварително проверена цел |
Auto невинаги е най-евтиният избор. Ако знаете, че дадена цел работи с single + unblocker, директното извикване на Single струва 2 кредита с предвидимо latency. 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 (държавно ограничение, което искате да игнорирате, 404 или 410 на премахната страница), ги разрешете чрез validate.status.accept:
{
"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- изискваше ротация на проксита за преминаване.browser- изискваше пълно рендиране в браузър, евентуално с решаване на предизвикателство.cache- повторно използвана топла сесия от предишно auto извикване. Най-евтиният път при повторни извиквания.warmup- сайтът предостави началната си страница, но ограничи вътрешния URL адрес, така че auto първо изтегли началната страница, запази върнатите бисквитки и изпрати нова заявка с тях. Сесията, която се запазва от това стъпало, не е обвързана с конкретен изход, така че последващите извиквания попадат на евтините стъпала.fail- никое стъпало не върна отговор, приет от вашите правила.
meta.solved: true означава, че по време на извикването е била срещната и изпълнена страница с предизвикателство. meta.attempts показва броя опити на подизвиквания преди успеха. За подробности разгледайте полето defense, което връщат единичните и прокси стъпалата: вижте Site checks.
Ако даден сайт продължава да завършва на browser, когато сте очаквали probe, преценете дали по-строго правило за validate (или по-малко строго) не би позволило на по-евтино стъпало да премине. Имайте предвид, че forceProxy по подразбиране е true, така че сондата за директен изход се прескача, освен ако не я изключите.
Какво изразходва едно извикване
meta.attemptsByEngine отчита заявките, изпратени от извикването към всяка машина, същите заявки, които панелът Auto attempts показва във вашия Overview. meta.browserRequests отчита тези, които са заели слот от дневния ви лимит за браузър.
"meta": {
"rung": "browser",
"solved": true,
"attempts": 7,
"credits": 47,
"attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
"browserRequests": 2
}
| Поле | Тип | Описание |
|---|---|---|
meta.attemptsByEngine |
object | Заявки, изпратени до single, proxy и browser. Browser заявка, отхвърлена от вашия план, се отчита тук, тъй като е била изпратена. |
meta.browserRequests |
number | Browser заявки, които са заели слот от дневния ви лимит. Browser заявка, отхвърлена от вашия план, не заема нищо. |
meta.attempts отчита стъпките на ескалацията, така че не винаги е равен на сумата от meta.attemptsByEngine. Една стъпка може да изпрати Single request и след това Proxy request, а стъпка, чийто browser вече е затворен за деня, не изпраща нищо.
Текущият ви брой за деня се предава в хедърите X-FourA-Browser-Used-Today и X-FourA-Browser-Limit-Per-Day: вижте Response Headers.
Грешки и гранични случаи
Когато auto се провали, отговорът съдържа status (обикновено статусът на последната неуспешна стъпка) и низ error:
{
"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 | Сайтът отказа заявката: разпозната е проверка за ботове, страницата беше предизвикателство или сайтът отговори с 401, 403, 429 или 503 |
contentRejected |
integer | Страницата беше изтеглена и само вашето правило validate я отхвърли |
statusRejected |
integer | Сайтът отговори със статус, който вашата заявка не приема, като например 404 за премахната страница |
other |
integer | Неуспешно изпълнение по друга причина, например сървърна грешка |
vendors |
string[] | Доставчици на проверки за ботове, разпознати при отказите, срещнати от извикването |
summary |
string | Едно изречение, съставено от броячите, безопасно за логване. Посочва HTTP статуса, с който сайтът е отговорил, когато не е разпознат доставчик, и отбелязва кога дневният ви лимит за браузър е бил изчерпан, така че не е могъл да се отвори браузър. |
Полетата съответстват на отчета при неуспешно Proxy извикване, без profilesTried. Две неща се различават. Proxy брои всеки изходен възел, който е опитал, до зададения от вас maxTries, а Auto брои собствените си заявки. Auto също така прочита страницата и нейния статус, така че отказът се отчита под defense дори когато не е разпознат доставчик. Бройка под contentRejected е тази, която можете да коригирате сами: страницата се върна, но правилото ви не съвпадна с нея.
Когато лимитите на вашия план срещнат стълбицата
Под-извикванията на 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: 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 извиквания достига лимита за конкурентност с по-малко заявки, отколкото бихте очаквали. Изпълнение на заявки в паралел описва оразмеряването на пакета.
Какво не прави Auto
- Не променя правните ограничения. Ако даден сайт откаже всеки изходен възел, до който FourA има достъп, auto връща този отказ.
- Не кешира съдържание. Всяко извикване достига до целта. "Warm session" представлява проксито и бисквитките (cookies), а не самият отговор.
- Това е един ред в Дневника на активността, под полученото ID на заявката, със сбора от кредитите на подповикванията. Отворете го и подповикванията от тип Single / Proxy / Browser, които auto е направил от ваше име, ще бъдат изброени като негови опити, всеки със собствен резултат. Те се броят към вашите лимити за Single, Proxy и Browser, никога към броя заявки или процента на успеваемост.
Свързани
- Крайни точки на API: Пълна справка за параметрите
- Избор на правилната крайна точка: Кога да изберете auto пред single, proxy или browser
- Резултати от заявките: Кои резултати подлежат на таксуване
- Защитени сайтове: Какво прави FourA при сайтове, които проверяват кой подава заявката
- Проверки на сайтове: Полето
defenseзадmeta.solved - MCP Рецепти: Същите модели като извиквания на MCP инструменти
- Ограничения на скоростта: Лимитите на плана, спрямо които се измерват подповикванията на auto