Справочник за API endpoints
Справочник за всички FourA API endpoints с параметри на заявката и формати на отговора.
Базов URL
https://eu.api.foura.ai/api
Автентикация
Всяка заявка изисква вашия API ключ в заглавката X-API-Key:
curl -X POST https://eu.api.foura.ai/api/single/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method": "GET", "url": "https://example.com"}'
Създавайте и управлявайте API ключове в Dashboard. Ключовете използват префикса pk_live_.
Response Headers
Отговорите от /api/* съдържат два корелационни header-а:
| Header | Value | Description |
|---|---|---|
X-FourA-Request-Id |
UUID | Уникален ID, присвоен на дадения request. Връща се при всеки response, включително 4xx и 5xx, с изключение на body, което FourA изобщо не може да прочете: 400 Invalid JSON in request body и 413 се отхвърлят преди присвояване на ID. Записвайте го в логовете от ваша страна. |
X-FourA-Credits |
integer | Кредити, изразходвани за този request. Връща се при всеки response, достигнал до engine, независимо дали е успешен или неуспешен (работата е извършена и в двата случая). Извикване, което FourA отхвърли преди стартиране от engine (липсващ или невалиден ключ, лимит на план или платформа, отказан target или proxy ID), не съдържа такъв. Вижте Request Outcomes за информация кои резултати се таксуват. |
Същият request ID служи за индексиране на прегледа на request и response payload в Activity Log в Dashboard (пазят се 24 часа, последните 200 за ключ), за да можете да намерите точния request по-късно и да го пуснете отново от Activity директно в Playground. Включете го при връзка с поддръжката, за да бъде открит даденият request за секунди.
$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method": "GET", "url": "https://example.com"}'
HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...
Вижте Response Headers за пълния списък и съвети за употреба.
Endpoints
Използвате тези endpoints през MCP? Сървърът
@fouradata/mcpобхваща и четирите endpoints като нативни MCP инструменти (foura_auto,foura_single,foura_proxy,foura_browser) със същите входни структури плюсoffload_largeопция за оптимизирана обработка на големи отговори откъм токени. Разликите:foura_browserняма полеlean, аfoura_proxyвсе още не приема полетата за exit location.
FourA предоставя четири endpoints за заявки, всеки оптимизиран за различен сценарий:
| Endpoint | Подходящ за |
|---|---|
POST /auto/ |
Smart fetch. Подавате URL, FourA избира най-евтиния работещ път (ротирано proxy или браузър, плюс директна заявка с forceProxy: false) и запомня кое работи за всеки хост. |
POST /single/ |
Бързи HTTP заявки, статични страници, APIs |
POST /proxy/ |
Защитени сайтове с автоматична ротация на proxy, опционално задаване на държава, видима за таргета |
POST /browser/ |
Страници, рендирани с JavaScript, SPAs |
GET /profiles |
Каталогът с браузърни профили за single и proxy. Публичен, без API ключ. |
За по-подробен преглед кога кой да изберете, вижте Choosing the Right Endpoint и Smart Fetch guide.
Ограничения за целевия URL
Цели, които се резолвват до частни, loopback или резервирани IP диапазони (RFC 5735, RFC 6598, IPv6 резервирани блокове), се отхвърлят с грешка 400 преди заявката да напусне FourA. Препращат се само публични хостнейми и IP адреси.
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
Цел към собствения API хост на FourA (eu.api.foura.ai или api.foura.ai) също се отхвърля с 400 на всички четири endpoints, преди изобщо нещо да бъде извлечено или таксувано. URL с интервал или контролен символ в него се отхвърля с 400 при Single, Proxy и Auto по същия начин; кодирайте интервала като %20 (Browser го извлича по начина, по който го прави Chrome). Единствената страница там, която FourA извлича, е /inspect.
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
Smart Fetch (Автоматично)
POST /api/auto/
Подавате URL и незадължителни validate правила. FourA преминава през оптимизирана по разход стълбица (ротирано proxy, след това пълен браузър) и спира на първото стъпало, което връща отговор, приет от вашите правила. С forceProxy: false първо се изпълнява евтина директна проверка. При повторни извиквания към същия хост вместо това се преизползва топла сесия, така че вторият опит е евтин.
Не настройвате повторни опити, размери на пула или брой проксита. FourA ги научава за всеки хост.
Тяло на заявката
| Параметър | Тип | Задължителен | По подразбиране | Описание |
|---|---|---|---|---|
url |
string | Да | - | Целеви URL |
method |
string | Не | "GET" |
HTTP метод |
headers |
[string, string][] | Не | - | Headers за изпращане към целта като двойки [name, value]. Всяко стъпало ги изпраща, с изключение на стъпалото с браузър. Изпратен от вас Cookie достига до сайта непроменен, а бисквитките от запазена сесия се добавят до него само под имена, които не сте изпратили. userAgent от запазена сесия заменя вашия User-Agent. Стъпалото с proxy пропуска условни headers като If-None-Match, освен ако вашият validate.status.accept не включва 304. |
data |
any | Не | - | Тяло на заявката за non-GET заявки |
validate |
object | Не | - | Критерии за успех, със същата структура като validate на Single Request (вижте по-долу). Укажете на автоматичния режим как изглежда реалната страница, за да може да различи съдържание от страница с предизвикателство. |
returnSession |
boolean | Не | true |
Включване на успешната сесия (proxy, cookies, userAgent) в отговора, за да можете да я преизползвате чрез /api/single/ или /api/browser/. |
forceProxy |
boolean | Не | true |
Винаги пренасочвай през ротиращо proxy. Задайте false, за да позволите по-евтиния директен път, когато целта го позволява (някои защити са по-строги към трафика от proxy). |
timeout_ms |
integer | Не | 120000 |
Общ лимит за време за цялото извикване в милисекунди. Всички подобласти се изпълняват в рамките на този бюджет. Мин. 5000, макс. 180000. |
ignoreProxies |
string[] | Не | - | Proxy ID-та, които да се избягват при всеки побопит. Използвайте ID-та, върнати от предишни отговори на /api/auto/ или /api/proxy/. |
followRedirects |
integer | Не | 5 |
Максимален брой пренасочвания за следване при евтините стъпала на стълбицата. 0 за деактивиране. Макс. 20. |
exitClass |
string | Не | - | standard или premium, както при Proxy Request. 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 |
number | HTTP статус от целевия ресурс. |
data |
string | Текст на тялото на отговора, независимо кое стъпало го е обслужило. Страница с JSON се връща като JSON текст, така че го парсвате сами. |
headers |
array or object | Заглавки на целевия отговор. Стъпалата Single и proxy връщат масив от обекти със заглавки за всеки hop; стъпалата с браузър връщат плосък обект. |
meta.rung |
string | Кое стъпало от стълбицата е доставило отговора. Едно от: probe (евтина директна заявка, само с forceProxy: false), proxy (ротиращо прокси), browser (пълно рендиране в браузър), cache (повторно изпълнена топла сесия), warmup (първоначално е изтеглена началната страница на сайта и нейните бисквитки са отворили вътрешния URL) или fail (нито едно стъпало не е върнало приет отговор). |
meta.solved |
boolean | Дали страницата е изисквала допълнителна стъпка (challenge страница) и тя е била изпълнена по време на това извикване. |
meta.attempts |
number | Междинни опити, направени преди успеха. |
meta.credits |
number | Общо изразходвани кредити за това извикване. Съвпада с X-FourA-Credits. |
meta.attemptsByEngine |
object | Изпратени заявки до single, proxy и browser. Заявка с браузър, отказана от вашия план, се брои, тъй като е била изпратена. |
meta.browserRequests |
number | Заявки с браузър, които са използвали слот от дневния ви лимит. Заявка с браузър, отказана от вашия план, не използва нищо. |
meta.exitClass |
string | Кой изходен клас е доставил отговора, налично когато заявката е посочила exitClass: premium или standard. Същата стойност се предава в заглавката за отговор X-FourA-Exit-Class. |
session.proxy |
string | Кодиран идентификатор на проксито, което е доставило отговора. Използвайте го повторно при заявка Single или Browser. Налично, когато returnSession е true. |
session.cookies |
array | Бисквитки за повторно използване, всяка от които има поне name и value. Стъпало с браузър връща хранилището за бисквитки на браузъра. Стъпало с прокси или директна проверка връща само бисквитките, които са отворили страницата (като тези, зададени от страницата за проверка на сайта), никога всички бисквитки, които страницата е задала, така че списъкът може да бъде празен. Налично, когато returnSession е true. |
session.userAgent |
string | User-Agent, използван при успешния опит. Налично, когато returnSession е true. |
error |
string | Съобщение за грешка, ако извикването е неуспешно. |
attemptReport |
object | При неуспешно извикване: заявките на енджина, върнати без страницата, групирани по причина. Вижте Smart Fetch. |
Пример
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"]}}
}'
Бележки
- Auto работи като координатор. Той извиква вътрешно Single, Proxy или Browser и препраща вашия API ключ към всяко подизвикване. Извикването на Auto е една заявка във вашия Activity Log и във вашия Overview със сбора от кредитите на неговите подизвиквания; подизвикванията са изброени под него като негови опити и никога не се отчитат като самостоятелни заявки.
- Подайте
validate.data.acceptс подниз, който се съдържа само в реалната страница. Без него auto не може да различи реален статус 200 от интерстициална страница за проверка, върната със статус 200. - Премахната страница е отговорът на сайта, а не отказ за достъп. Когато две изходни точки върнат еднакъв
404или410и вашиятvalidateне го приема, извикването завършва с тозиstatusи сerror, който започва сthe site answered. Посочете статуса вvalidate.status.acceptи Auto връща първия отговор с този статус, който отговаря на останалите условия във вашияvalidate. Същото важи и за всеки друг статус, посочен там, с изключение на403,429,503и202, които сайтовете изпращат и заедно със страница за проверка. timeout_msограничава цялото извикване. Първоначален студен достъп до защитен сайт може да отнеме десетки секунди; повторно използваните загрети сесии обикновено завършват за по-малко от секунда.
exitClass при Smart Fetch
exitClass работи при Smart Fetch по същия начин, както при Proxy Request: разрешение, а не директна инструкция. Auto опитва първо стандартния пул. Когато стандартният пул не може да достигне страницата и заявката съдържа premium, Auto отваря страницата в браузър през премиум изходна точка. Сесията, която изгражда там, обслужва следващите ви извиквания към същия сайт, които също съдържат premium; извиквания, които не го съдържат, никога не я използват.
Изчерпването на лимита не е грешка. След като премиум трафикът във вашия план бъде изразходван за отчетния период, извикването продължава в стандартния пул и meta.exitClass показва standard. При план без премиум изходни точки, извикване, което изпраща exitClass: premium, се отхвърля с 403, носещ X-FourA-Limit: plan_limit_premium, преди да бъде извършена каквато и да е работа.
Премиум трафикът се измерва както при Proxy Request. Страница, отворена в браузър, зарежда повече от самата страница, затова премиум Smart Fetch страница използва повече премиум трафик от същата страница, извлечена чрез Proxy Request. За да се ограничи това, премиум Smart Fetch страница се зарежда без изображения, шрифтове и мултимедия, както и без скриптове от познати доставчици на реклами, анализи и съгласие за бисквитки.
Single Request
POST /api/single/
Изпраща HTTP заявка с реалистични мрежови характеристики, подобни на браузър, без да стартира реален браузър. Това е най-бързият endpoint.
Тяло на заявката
| Параметър | Тип | Задължителен | По подразбиране | Описание |
|---|---|---|---|---|
method |
string | Да | - | HTTP метод: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
url |
string | Да | - | Целеви URL. Използвайте {ts} където и да е в URL адреса, за да вмъкнете текущия времеви маркер за избягване на кеширането. |
headers |
[string, string][] | Не | - | Персонализирани заглавки като двойки [name, value] |
unblocker |
boolean | Не | true |
Изпращане на реалистични заглавки на браузър (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Включено по подразбиране. Задайте false и FourA няма да добавя заглавки на браузър, а само подадените от вас. |
timeout_ms |
number | Не | 15000 | Общ таймаут в ms (макс: 120000) |
connect_timeout_ms |
number | Не | 5000 | Таймаут за връзка в ms |
accept_timeout_ms |
number | Не | 5000 | Таймаут за приемане в ms (време за изчакване на приемане на връзката) |
server_response_timeout_ms |
number | Не | 15000 | Таймаут за отговор от сървъра в ms (време за изчакване на първия байт) |
dns_cache_timeout_sec |
number | Не | 120 | TTL на DNS кеша в секунди (макс: 240) |
followRedirects |
number | Не | изключено | Максимален брой пренасочвания за проследяване (0-20). Пропуснете го, за да го деактивирате. |
tryJsonData |
boolean | Не | false | Парсване на тялото на отговора като JSON, ако е възможно |
returnBuffer |
boolean | Не | false | Връщане на суров буфер вместо декодиран низ |
data |
any | Не | - | Тяло на заявката (низ или обект, автоматично сериализиран до JSON) |
proxy |
string | Не | - | Proxy ID от предишен отговор за фиксиране на същата изходна точка. Предайте обратно непрозрачния низ дословно. Суров proxy адрес се отхвърля с 400 Invalid proxy format. Някои ID не могат да бъдат фиксирани: вижте Фиксиране на изходна точка. |
browser |
string | Не | Chrome | Браузър за представяне: Chrome, Edge, Safari, Firefox или Tor. Вижте Профили на браузъра. |
os |
string | Не | - | Операционна система за представяне: Windows, macOS, Android или iOS. Името на фамилията приема всяка от нейните версии. |
version |
string | Не | newest | Версия на браузъра за представяне според каталога. Най-новото съвпадение печели, когато отговарят няколко. |
profile |
string | Не | - | Точно id на профил от GET /api/profiles, вместо трите полета по-горе. |
validate |
object | Не | - | Правила за валидиране на отговора (вижте по-долу) |
Профили на браузъра
По подразбиране заявката представя най-новия Google Chrome. Някои цели приемат един браузър и отказват друг, така че browser, os и version стесняват каталога от измерени профили, а profile избира такъв по id.
{
"method": "GET",
"url": "https://example.com",
"browser": "Firefox",
"os": "Windows"
}
Правила:
- Изборът изисква
unblocker(включено по подразбиране). При изключенunblockerне се изпращат browser headers, така че заявката се отхвърля, вместо да бъде приложена наполовина. - Когато съвпадат няколко профила, се избира най-новата версия.
- Комбинация, която каталогът не може да предостави, връща грешка с посочване на наличното, а неизвестен
profileid връщаunknown profile '<id>'. Заявката никога не се изпраща като друг браузър. - Същите четири полета са налични в обекта
requestнаPOST /proxy/.
GET /api/profiles връща пълния каталог и не изисква API key:
{
"profiles": [
{ "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
],
"default": "..."
}
osFamily е стойността за филтриране при изграждане на селектор; os запазва името на релийза за визуализация.
Правила за валидация
Обектът validate ви позволява да дефинирате условия за успех и неуспех. Ако условие в fail съвпадне, заявката се третира като неуспешна. Ако са зададени условия в accept, само съвпадащите отговори се третират като успешни.
{
"validate": {
"status": { "accept": [200, 201], "fail": [403, 503] },
"headers": { "accept": {"content-type": "application/json"} },
"data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
}
}
| Поле | Тип | Описание |
|---|---|---|
validate.status.accept |
number[] | HTTP статус кодове за приемане |
validate.status.fail |
number[] | HTTP статус кодове за отхвърляне |
validate.headers.accept |
object | Отговорът преминава успешно, когато поне една двойка съвпада при което и да е пренасочване (hop). Имената и стойностите съвпадат без значение на регистъра (case-insensitively), по част от текста. |
validate.headers.fail |
object | Двойки ключ-стойност на заглавки (headers), които предизвикват неуспех |
validate.data.accept |
string[] | Отговорът преминава успешно, когато тялото съдържа поне един от тези низове |
validate.data.fail |
string[] | Низове в тялото на отговора, които предизвикват неуспех |
Пример
curl -X POST https://eu.api.foura.ai/api/single/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"method": "GET",
"url": "https://example.com/products",
"timeout_ms": 10000
}'
Response:
{
"status": 200,
"headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
"data": "<!doctype html>...",
"total_time": 0.342
}
Когато целта изпълнява проверка за ботове преди зареждане на съдържанието, отговорът съдържа и обект defense, указващ доставчика и дали проверката е премината успешно:
{
"status": 200,
"data": "<!doctype html>...",
"total_time": 3.61,
"defense": {
"vendor": "sgcaptcha",
"solved": true,
"present": ["sgcaptcha"],
"ms": 3412,
"cookie": "_I_=<clearance>"
}
}
| Поле | Тип | Описание |
|---|---|---|
status |
number | HTTP статус код от целта |
headers |
array | По един обект за всяка стъпка на пренасочване. Всеки съдържа поле result със статус реда плюс всеки response header. Заглавки с множество стойности (Set-Cookie, Link, WWW-Authenticate) се връщат като масиви от низове. |
data |
string/object | Тяло на отговора (JSON ако tryJsonData е true) |
total_time |
number | Общо време на заявката в секунди |
proxy |
string | Кодиран ID на проксито, през което е преминала заявката (само когато в заявката е подаден proxy). Използвайте го повторно при следващо извикване, за да фиксирате същата изходна точка. |
defense |
object | Присъства, когато целта е изпълнила проверка за ботове при тази заявка или когато повторен опит с бисквитките на самия сайт е генерирал тялото. defense.solved показва дали проверката е премината, а defense.retry показва дали повторният опит е предоставил съдържанието. Вижте Проверки на сайта за всяко поле и пълния списък със системи. |
error |
string | Съобщение за грешка, ако заявката е неуспешна |
Proxy Request
POST /api/proxy/
Пренасочва вашата заявка през ротиращи проксита с автоматичен повторен опит при грешка. Опционално ограничете избора до списък от изходни държави, видими за целта.
Тяло на заявката
| Параметър | Тип | Задължителен | По подразбиране | Описание |
|---|---|---|---|---|
request |
object | Да | - | Тяло на единична заявка (същите полета като Single Request по-горе) |
timeout_ms |
number | Не | 45000 | Общ timeout за всички опити в ms (макс: 120000) |
maxTries |
number | Не | 5 | FourA спира стартирането на нови опити, щом толкова на брой се провалят (макс: 90). Опитите се изпълняват паралелно, така че могат да завършат с няколко повече от това число. |
ignoreProxies |
string[] | Не | - | Proxy ID за изключване от ротацията (използвайте ID, върнати от предишни отговори) |
exitCountries |
string[] | Не | - | Стриктен allowlist от двубуквени кодове на държави, видими за целевия хост (напр. ["CZ", "GB"]). Стойностите се изчистват от интервали, преобразуват се в главни букви и се дедупликират. Изходите от стандартния пул с неизвестна държава се изключват, като стандартният пул никога не превключва към незаявена държава. Премиум изходът също произлиза от някоя от посочените държави. |
exitClass |
string | Не | - | standard или premium. premium позволява на заявката да ескалира до премиум изход, когато стандартният пул се затруднява със защитена цел. Изисква план, който включва премиум изходи. |
exitState |
string | Не | - | Регион, от който произлиза изходът. Изисква exitClass: premium и точно една държава в exitCountries. Вижте Exit location. |
exitCity |
string | Не | - | Град, от който произлиза изходът. Изисква exitClass: premium и точно една държава в exitCountries. |
exitAsn |
string | Не | - | Мрежа, от която произлиза изходът, по AS номер, например 8866. Изисква exitClass: premium и точно една държава в exitCountries. |
exitOs |
string | Не | - | windows, android, ios или mac: типът устройство, на което принадлежи адресът. Изисква exitClass: premium. |
exitLifetimeMin |
integer | Не | - | Минути, през които изходът запазва адреса си, от 3 до 1440. Изисква exitClass: premium. |
Обхват на exitCountries
Изборът използва най-новите налични метаданни за видимата за целта държава, обновявани обикновено в рамките на около десет минути. Това не е геолокационно търсене на живо по време на заявката. Не съдете за обслужващата държава по хост адреса на proxy сървъра.
Ако текущият пул няма съвпадение за заявените държави и заявката не посочва exitClass: premium, отговорът връща HTTP 200 с error обвивка:
{
"error": "No eligible proxy found for exit countries: CZ, GB",
"code": "no_eligible_proxy",
"details": { "exitCountries": ["CZ", "GB"] },
"total": 0.084
}
Запазете заявения обхват и опитайте отново по-късно. Променете или го разширете само когато изискването за държава на вашия работен процес изрично се промени.
Пример
curl -X POST https://eu.api.foura.ai/api/proxy/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"maxTries": 3,
"exitCountries": ["CZ", "GB"],
"request": {
"method": "GET",
"url": "https://example.com/prices"
}
}'
Response:
{
"status": 200,
"headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
"data": "<!doctype html>...",
"total_time": 1.204,
"proxy": "A1B2C3",
"exitCountry": "CZ",
"total": 2.341
}
| Поле | Тип | Описание |
|---|---|---|
proxy |
string | Кодиран идентификатор на използваното прокси. Използвайте го повторно при Single или Browser заявка, като го подадете като полето proxy, или го пропуснете при следващата Proxy заявка чрез ignoreProxies. |
exitCountry |
string | Двубуквен код на държавата (видим за целта) на проксито, обслужило заявката. Наличен е само когато заявката е задала exitCountries, независимо кой клас exit точка я е обслужил. Винаги проверявайте дали е един от кодовете, които сте заявили, преди да се доверите на отговора. |
exitClass |
string | Кой клас exit точка е обслужил тази заявка, наличен при успешен отговор, когато заявката е посочила такъв. premium означава, че премиум exit точка е върнала тялото; standard означава, че стандартният пул го е направил. Неуспешното извикване не е обслужило нищо, така че не съдържа exitClass; вижте неговия attemptReport за това какво са срещнали опитите. |
total |
number | Външна продължителност по астрономическо време в секунди (float). Включва избора на прокси, повторните опити и успешния опит. total_time е само вътрешната заявка; total винаги е >= total_time. |
profile |
string | Профилът на браузъра, избран от ротацията, наличен само когато не е бил този, който сте поискали. Липсата му означава, че заявката е изпратена точно както е описана. Подайте обратно идентификатора като profile при последващи извиквания, за да запазите браузъра, който е сработил. |
error |
string | Съобщение за грешка, ако заявката е неуспешна. При несъответствие на обхвата (scope miss), code е no_eligible_proxy и details.exitCountries повтаря нормализирания scope. |
attemptReport |
object | Наличен при всяко неуспешно Proxy извикване. Отчита какво са срещнали опитите, така че блокиран пул, неактивен пул и правило validate, което никога не е съвпаднало, да не изглеждат като една и съща грешка. Вижте по-долу. |
request |
object | Наличен при неуспешно Proxy извикване: заявката, която FourA е изпълнил, с попълнени стойности по подразбиране и вашите ignoreProxies точно както сте ги изпратили. |
Всички полета за отговор от Single Request също са включени, включително defense: опит за прокси връзка, който е срещнал проверка за ботове, го докладва по същия начин, както Single.
Защо дадено Proxy извикване е било неуспешно
Download maxTry limit reached изглежда по един и същи начин независимо от изхода на опитите, затова всеки неуспешен Proxy отговор съдържа attemptReport до грешката:
{
"error": "Download maxTry limit reached",
"attemptReport": {
"total": 25,
"noResponse": 0,
"defense": 0,
"contentRejected": 25,
"statusRejected": 0,
"other": 0,
"vendors": [],
"profilesTried": ["default"],
"summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
},
"total": 34.812
}
| Поле | Тип | Описание |
|---|---|---|
total |
integer | Направени опити |
noResponse |
integer | Exit възелът не отговори, така че сайтът никога не беше достигнат |
defense |
integer | Сайтът отговори и при този отговор беше разпозната проверка за ботове |
contentRejected |
integer | HTTP 200, без проверка за ботове, отхвърлен само от вашия validate.data |
statusRejected |
integer | Сайтът отговори, без проверка за ботове, отхвърлен от вашия validate.status |
other |
integer | Получен е отговор, нито едно от горните |
vendors |
string[] | Доставчици на проверки за ботове, разпознати в рамките на задачата |
profilesTried |
string[] | Браузърни профили, изпратени от задачата, подредени по първо използване. default означава, че вашата заявка е изпратена непроменена. |
summary |
string | Едно изречение, съставено от броячите, безопасно за логване |
Стрингът error остава непроменен, така че клиент, който прави съпоставка по него, продължава да работи. Какво да направите за всеки брояч: Защо proxy request изчерпа опитите.
exitClass
Някои цели отказват връзка от exit възлите в стандартния пул, независимо колко опита са направени. exitClass: premium указва на Proxy, че може да ескалира такава заявка към premium exit в допълнение към стандартния пул, вместо само да ротира в рамките на него.
{
"exitClass": "premium",
"request": { "method": "GET", "url": "https://example.com/report" }
}
Три неща си струва да знаете, преди да го изпратите.
Това е позволение, а не инструкция. Стандартният pool все пак се състезава за отговора и обикновено печели. Премиум изход се включва само когато pool-ът е изчерпал кратък бюджет за заявката или целта видимо я е отказала. Заявка, на която стандартният pool отговори преди да е бил опитан какъвто и да е премиум изход, е нормален успех и не ви струва премиум трафик. След като премиум изход бъде опитан, неговият трафик се отчита, както е описано по-долу.
Премиум изходът остава в рамките на exitCountries. При списък с държави, премиум изходът излиза от една от тези държави и exitCountry в отговора я посочва, както при стандартния pool.
Отговорът ви казва какво всъщност ви е обслужило. Когато посочите клас, отговорът връща обратно exitClass:
{
"status": 200,
"exitClass": "premium",
"proxy": "Y2QXVK",
"data": "..."
}
premium означава, че premium изход е върнал тялото. standard означава, че стандартният пул го е направил, което е и отговорът, който получавате, когато не е могъл да се осигури premium изход, както и когато включеният във вашия план premium трафик (плюс всичко допълнително закупено) е изчерпан за периода на фактуриране. Нито едно от двете не е грешка и можете да сверявате своя premium трафик спрямо тях за всяка заявка, вместо спрямо месечна стойност. Същата стойност се предава в X-FourA-Exit-Class response header (вижте Response Headers).
Premium трафикът се измерва на ниво мрежа. Всеки premium опит отчита изпратеното и полученото при преминаването през мрежата, компресирано и криптирано в процеса, независимо дали е върнал вашата страница или не. Опит, който все още се изпълнява, когато друг изход отговори, се спира веднага, а трафикът, който е пренесъл до този момент, също се отчита. Premium трафикът се отчита към вашия premium лимит, както и в общия ви трафик: едни и същи байтове, отчетени два пъти, без никога да се събират заедно. Когато premium изход е доставил страницата, неговият трафик представлява целият трафик на заявката, така че страницата не се отчита повторно като стандартен трафик. Вашата страница Usage & Limits показва общия трафик, premium дела от него и premium лимита, спрямо който се измерва потреблението ви.
Пропускането на полето и изпращането на standard запазват заявката в стандартния пул: само premium позволява premium изход. Успешна заявка, която посочва клас, получава обратно exitClass в отговора, а заявка, която пропуска полето, не получава.
Изчерпването не е грешка. Заявка, посочваща premium след изчерпване на лимита, продължава да работи: стандартният пул я обслужва и отговорът съдържа standard. Единственото изключение е заявка, която посочва exit location: стандартният пул не може да я изпълни, затова тя бива отказана.
exitClass: premium изисква план, който включва premium изходи. При план без такива заявката никога не изразходва premium изход: тя бива отказана с код 403 и съобщение X-FourA-Limit: plan_limit_premium (вижте Rate Limits), преди да се извърши каквато и да е работа.
Изходна локация
Premium изход може да излиза от определено място в дадена държава и да запази адреса си толкова дълго, колкото ви е необходимо:
{
"exitClass": "premium",
"exitCountries": ["BG"],
"exitCity": "sofia",
"exitLifetimeMin": 15,
"request": { "method": "GET", "url": "https://example.com/" }
}
Отговорът посочва изходната точка и държавата, от която е осъществен изходът:
{
"status": 200,
"exitClass": "premium",
"exitCountry": "BG",
"proxy": "1EM4GZY",
"data": "..."
}
Това proxy ID запазва всичко от него. Подайте го на Single или Browser и заявката тръгва от същото място, без друго поле до него. Вижте Pinning an Exit.
Правила:
- Всяко от
exitState,exitCity,exitAsn,exitOsиexitLifetimeMinизпраща заявката само през premium изходи. Стандартният пул не получава опит, тъй като не може да ги изпълни. - Те изискват
exitClass: premium. Без него заявката се отхвърля с грешка 400, която посочва полето. exitState,exitCityиexitAsnсъществуват в рамките на една държава, така че изискват точно една държава вexitCountries.exitOsиexitLifetimeMinработят с няколко: изходът поема една от тях, аexitCountryв отговора указва коя.exitState,exitCity,exitAsnиexitOsизискват план с геотаргетиране, както и premium изходи.- При изчерпан premium трафик заявката се отхвърля с 403 с
X-FourA-Limit: plan_limit_premium, тъй като стандартният пул не може да я обслужи. - Ако нито един premium изход не отговори за това местоположение, отговорът е обвивка за грешка като тази под exitCountries scoping, с грешка
No premium exit answered for this requestиcode: no_eligible_proxy.details.exitCountriesприсъства, когато сте изпратили списък с държави.
Стойностите са тези, които proxy port приема за state, city, asn и os.
Ротация на браузърни профили
Proxy ротира изходите. Когато сайт отхвърли браузъра, представен от FourA, вместо изхода, от който идва, Proxy преминава и към друга фамилия браузъри от каталога. Това не добавя нов опит: ротацията променя какво изпраща повторният опит, но никога дали такъв ще се извърши.
Proxy също така запомня за известно време фамилията, която сайтът последно е приел, така че следващо повикване към същия сайт може да започне с тази фамилия вместо с подразбиращата се. Отговорът я посочва в profile, както прави за всяка фамилия, избрана от ротацията.
Изрично посочено profile, browser, os или version върху вътрешния ви request никога не се презаписва, както и заявка, която носи собствен User-Agent или Cookie заглавен блок, тъй като разрешението е обвързано със сигнатурата, която го е заслужила.
Браузърна заявка
POST /api/browser/
Отваря вашия URL в Chrome браузър инстанция. Страницата се зарежда, JavaScript се изпълнява и получавате напълно рендирания HTML плюс бисквитките.
Тяло на заявката
| Параметър | Тип | Задължителен | По подразбиране | Описание |
|---|---|---|---|---|
url |
string | Да | - | Целеви URL |
headers |
object | Не | - | Персонализирани хедъри като двойки ключ-стойност |
cookies |
array | Не | - | Бисквитки за задаване: [{name, value, domain?}] |
userAgent |
string | Не | - | Персонализиран User-Agent низ |
unblocker |
boolean | Не | true |
Изпълнява проверката, изисквана от страницата преди зареждане (challenge страница или подобна защита). Включено по подразбиране. Задайте false, за да рендерирате върнатото от страницата точно както е получено, включително challenge страница. |
proxy |
string | Не | - | Proxy ID от предишен отговор за фиксиране на същия изходен възел. Върнете непрозрачния низ дословно. Директен proxy адрес се отхвърля с 400 Invalid proxy format. |
timeout_ms |
number | Не | 30000 | Време за изчакване при зареждане на страницата в ms (макс: 120000) |
checkStatus |
number | Не | - | Очакван HTTP статус (заявката се проваля, ако е различен) |
checkText |
string | Не | - | Текст, който задължително трябва да присъства в рендерираната страница |
lean |
boolean | Не | false |
Пропуска изображения, шрифтове, мултимедия и заявки към познати услуги за реклами, анализи, съгласие за поверителност и социални мрежи. Самата страница, нейните скриптове, стилове и всичко необходимо за стъпка по верификация продължават да се зареждат. Използвайте го, за да намалите генерирания трафик, например през фиксиран премиум изходен възел. |
Синхронизиране на часовника на браузъра с изходния възел
Дадена страница може да прочете часовата зона на браузъра и да я сравни с държавата на IP адреса, който засича. Несъответствието е един от най-лесните за засичане сигнали от бот детектори, а отстраняването му не изисква никакви усилия.
Не е необходимо да правите нищо. FourA разчита държавата от proxy ID, а браузърът връща съответстващата ѝ часова зона.
- Това е държавата на изходния възел, тоест държавата, която целта вижда, а не мястото, където се хоства проксито. Двете стойности се различават достатъчно често, за да имат значение.
- Когато FourA не знае държавата на изходния възел, часовникът на браузъра остава непроменен вместо да се правят предположения. Премиум изходен възел има известна държава, когато сте заявили конкретна с
exitCountriesв Proxy Request. - Единствено часовникът следва държавата.
Accept-Languageи съдържанието, което сайтът предоставя, остават непокътнати, така че страницата няма да смени езика си неочаквано.
Параметърът userAgent
Изпратете userAgent и страницата, нейните уеб уъркъри и целевият сървър ще видят точно този низ. FourA извлича и съответстващите client hints от него (sec-ch-ua, sec-ch-ua-platform, navigator.platform и стойностите с висока ентропия, които детекторът изисква по име), предотвратявайки разминаване между браузъра в хедъра и в JavaScript.
Върнатият userAgent в отговора е този, който е бил реално подаден. Това е важно при повторно подаване на верификация: бисквитката cf_clearance е обвързана с изходния възел и със съответния User-Agent, който я е получил, затова върнете обратно низа от отговора, а не този, който предполагате, че е бил използван. Вижте Site checks.
Изпратете низ, който не е на Chromium (например User-Agent на Firefox), и той ще бъде предаден без промяна, без прикрепен списък с брандове на Chromium.
Пример
curl -X POST https://eu.api.foura.ai/api/browser/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/spa-app",
"timeout_ms": 15000,
"checkText": "product-list"
}'
Response:
{
"status": 200,
"headers": {"content-type": "text/html"},
"body": "<!doctype html>...",
"cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
"userAgent": "Mozilla/5.0...",
"defenseSolved": true,
"defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
| Поле | Тип | Описание |
|---|---|---|
status |
number | HTTP статус код от целевия сайт |
headers |
object | Response хедъри |
body |
string or object | Напълно рендерирано съдържание на страницата. String HTML, когато content-type е HTML; object, когато страницата е върнала JSON и е била автоматично парсната. |
cookies |
array | Пълни cookie обекти от страницата. Всяко cookie включва name, value, domain, path, expires, httpOnly, secure, sameSite и други cookie свойства. |
userAgent |
string | Използван User-Agent на браузъра |
defenseSolved |
boolean | true, ако при това извикване е била срещната и успешно премината защита от ботове, false в противен случай. Определя дали извикването струва 5 или 10 кредита. |
defenses |
object | present изброява всички вендори, разпознати по време на зареждането на страницата, а cleared изброява тези, чието преминаване е отразено във финалната страница. Вендор може да присъства в present и никога в cleared. Вижте Site checks. |
proxy |
string | Кодирано ID на проксито, през което е преминала заявката (само когато в заявката е подаден proxy). Използвайте го повторно в следващи извиквания, за да запазите същата изходна точка. |
error |
string | Съобщение за грешка, ако заявката е неуспешна |
Заковаване на изходна точка (Exit Pinning)
Стойност proxy в Single или Browser заявка заковава изходната точка, използвана от предишно извикване. Подайте обратно непрозрачното ID точно както е получено, никога реален адрес на прокси. ID от Proxy заявка, която е посочила държава, населено място или време на живот, ги запазва, така че закованата заявка не се нуждае от друго поле.
Три стойности се отхвърлят, всички с код 400:
| Грешка | Значение |
|---|---|
Invalid proxy format |
Стойността не е ID, издадено от FourA. Суров адрес на прокси води до тук. |
Proxy not found |
ID е декодирано, но вече не съответства на активна изходна точка. Вземете ново от ново извикване. |
Managed exit: this proxy id cannot be pinned to a request |
Изходната точка съществува, но не е такава, която FourA ще поддържа отворена за именувана заявка. ID на премиум изходна точка води до тук, когато планът ви няма останал премиум трафик за изразходване. Използвайте отново сесията, с която е върната, или изпълнете извикването през POST /api/proxy/ и вземете изходната точка, която системата избере. |
Закована премиум изходна точка се таксува като премиум трафик. Отговорът съдържа X-FourA-Exit-Class: premium, за да можете да го проследявате за всяка заявка, а трафикът, преминал през изходната точка, се отчита както към премиум трафика на страницата Usage & Limits, така и към общия ви трафик, независимо дали сайтът е върнал желаната страница. Заковаването изисква премиум изходни точки във вашия план и оставащ лимит; в противен случай ID се отхвърля с горната грешка 400 за управлявана изходна точка.
HTTP статус кодове
| Код | Значение |
|---|---|
| 200 | Заявката е завършена (проверете вътрешния status за отговора от целевия адрес) |
| 400 | Невалидно тяло на заявката, параметри, целеви IP в частен/резервиран диапазон, целеви адрес върху API хоста на самия FourA, URL с неенкоднат интервал в него (Single, Proxy, Auto) или proxy ID, което не може да бъде фиксирано. При Single, Proxy и Browser поле, което не преминава валидация, се посочва с име: Invalid request: <field>: <reason>, до пет полета. Не се таксува. Auto връща за същата грешка HTTP 200 и status: 400 в тялото. |
| 401 | Липсващ или невалиден API ключ |
| 403 | Endpoint адресът или даден параметър не е включен във вашия план. X-FourA-Limit посочва причината: plan_limit_feature или plan_limit_premium. |
| 404 | Not Found: на този път няма endpoint. |
| 413 | JSON тялото на заявката надвишава 100 KB. Отговорът не е JSON и не съдържа X-FourA-Request-Id. |
| 429 | Лимит на плана (зададен е X-FourA-Limit) или споделеният лимит за минута на платформата (без header) |
| 500 | Вътрешна грешка на сървъра |
| 502 | Upstream unavailable: FourA не успя да се свърже с машината си. Malformed JSON from backend: машината отговори, но FourA не успя да прочете отговора. Опитайте отново. |
| 503 | Услугата е временно деактивирана или претоварена, API key check temporarily unavailable когато FourA за момент не успя да потвърди ключа ви (опитайте отново след Retry-After), или Backend service unavailable докато дадена машина се рестартира. При Browser страницата изчаква до 10 секунди за свободен браузър, когато всички са заети, и получава Backend service unavailable, ако никой не се освободи за това време. |
| 504 | Upstream timeout. Машината не завърши в рамките на зададеното време за тази заявка. Увеличете timeout_ms или опитайте отново. |
Следващи стъпки
- Smart Fetch (Auto): Кога да оставите FourA да избере пътя вместо вас
- Избор на правилния endpoint: Кога да изберете ръчно Single, Proxy или Browser
- Удостоверяване: Управлявайте своите API ключове
- Обработка на грешки: Обработвайте грешките надеждно
- Проверки на сайтове: Прочетете полето
defenseи изпратете clearance повторно - Защо proxy заявката изчерпа опитите: Прочетете
attemptReportи предприемете действие - Ограничения на честотата: Запознайте се с лимитите за заявки
- Бърз старт: Първата ви заявка за 30 секунди