Справочник за 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, така че заявката се отхвърля, вместо да бъде приложена наполовина.
  • Когато съвпадат няколко профила, се избира най-новата версия.
  • Комбинация, която каталогът не може да предостави, връща грешка с посочване на наличното, а неизвестен profile id връща 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 или опитайте отново.

Следващи стъпки

Обновено: 13 ноември 2026 г.