Справочник за API Endpoints

Справочник за всички FourA API endpoints с параметри на заявката и формати на отговора.

Base URL

https://eu.api.foura.ai/api

Автентикация

Всяка заявка изисква вашия API ключ в header-а 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/* съдържат два correlation header-а:

Header	Стойност	Описание
`X-FourA-Request-Id`	UUID	Уникален идентификатор, присвоен на заявката. Връща се при всеки отговор, включително 4xx и 5xx, с изключение на тяло, което FourA не може да прочете изобщо: `400 Invalid JSON in request body` и `413` се отказват преди да бъде присвоен ID. Записвайте го в логовете от ваша страна.
`X-FourA-Credits`	цяло число	Кредити, изразходвани за тази заявка. Връща се при всеки отговор, достигнал до engine, независимо дали е успешен или неуспешен (работата е извършена и в двата случая). Извикване, отказано от FourA преди да бъде изпълнено от някой engine (липсващ или невалиден ключ, лимит на плана или платформата, отказана цел или proxy ID), не съдържа такъв. Вижте Request Outcomes за информация кои резултати са платими.

Същият request ID служи за идентификация при прегледа на request и response payload в Activity Log на Dashboard (пази се 24 часа, последните 200 на ключ), за да можете да намерите точната заявка по-късно и да я пуснете отново директно в Playground. Включете го, когато се свързвате с поддръжката, за да бъде открита заявката за секунди.

$ 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 като native MCP инструменти (foura_auto, foura_single, foura_proxy, foura_browser) със същата входна структура, плюс offload_large опция за оптимизирана обработка на големи отговори с оглед разхода на tokens.

FourA предоставя четири request endpoints, всеки оптимизиран за различен сценарий:

Endpoint	Най-подходящ за
`POST /auto/`	Smart fetch. Подавате URL, FourA избира най-евтиния работещ маршрут (direct, rotated proxy или browser) и запомня работещото решение за всеки host.
`POST /single/`	Бързи HTTP заявки, статични страници, APIs
`POST /proxy/`	Защитени сайтове с автоматична ротация на proxy, опционално насочване по държава, видима за целта
`POST /browser/`	Страници, рендерирани с JavaScript, SPAs
`GET /profiles`	Каталогът с browser profiles за `single` и `proxy`. Публичен, без API key.

За по-подробен преглед кога кой да изберете, вижте Choosing the Right Endpoint и ръководството за Smart Fetch.

Ограничения за целеви URL

Цели, които се преобразуват до частни, loopback или резервирани IP диапазони (RFC 5735, RFC 6598, IPv6 резервирани блокове), се отхвърлят с грешка 400, преди заявката да напусне FourA. Препращат се само публични hostnames и 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." }

Smart Fetch (Auto)

POST /api/auto/

Подавате URL плюс опционални validate правила. FourA преминава през оптимизирана по разход стълбица (евтина директна проба, ротирано proxy, пълен браузър) и спира на първото стъпало, което върне response, приет от вашите правила. При повторни извиквания към същия host се преизползва топла сесия, така че вторият hit е евтин.

Не настройвате опити за повторение, размери на пулове или брой proxy сървъри. FourA ги научава за всеки отделен host.

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`url`	string	Да	-	Целеви URL
`method`	string	Не	`"GET"`	HTTP метод
`headers`	[string, string][]	Не	-	Персонализирани headers като двойки [име, стойност]
`data`	any	Не	-	Request body за заявки, различни от GET
`validate`	object	Не	-	Критерии за успех, същата структура като `validate` на Single Request (вижте по-долу). Укажете на auto как изглежда истинската страница, за да може да различи съдържание от challenge страница.
`returnSession`	boolean	Не	`true`	Включва успешната сесия (`proxy`, `cookies`, `userAgent`) в response, за да можете да я преиграете през `/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/` responses.
`followRedirects`	integer	Не	`5`	Максимален брой пренасочвания за проследяване по евтините стъпала на стълбицата. `0` за деактивиране. Макс. `20`.

Response

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

Поле	Тип	Описание
`status`	number	HTTP статус от целевия ресурс.
`data`	string	Тяло на отговора като текст, независимо кое стъпало го е обслужило. Страница с JSON се връща като JSON текст, така че я парсвайте сами.
`headers`	array или object	Заглавни части (headers) на отговора от целевия ресурс. Единичните и proxy стъпалата връщат масив от обекти със заглавни части за всеки междинен преход; браузърните стъпала връщат плосък обект.
`meta.rung`	string	Кое стъпало от стълбицата е доставило отговора. Едно от: `probe` (евтина директна заявка), `proxy` (ротиращо proxy), `browser` (пълно рендиране в браузър), `cache` (повторно използвана активна сесия), `warmup` (началната страница на сайта е изтеглена първа и нейните бисквитки са отворили вътрешния URL) или `fail` (нито едно стъпало не е върнало приет отговор).
`meta.solved`	boolean	Дали страницата е изисквала допълнителна стъпка (страница с проверка/challenge) и тя е била завършена по време на това извикване.
`meta.attempts`	number	Направени подизпълнения преди успеха.
`meta.credits`	number	Общо изразходвани кредити за това извикване. Съответства на `X-FourA-Credits`.
`session.proxy`	string	Кодиран идентификатор на проксито, което е доставило отговора. Използвайте го повторно при заявка от тип Single или Browser. Присъства, когато `returnSession` е `true`.
`session.cookies`	array	Бисквитки от успешния опит. Присъства, когато `returnSession` е `true`.
`session.userAgent`	string	User-Agent, използван при успешния опит. Присъства, когато `returnSession` е `true`.
`error`	string	Съобщение за грешка, ако извикването е неуспешно.

Пример

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 от междинна страница с проверка (challenge interstitial), върната със статус 200.
timeout_ms ограничава цялото извикване. Първоначално студено зареждане на защитен сайт може да отнеме десетки секунди; повторно използваните активни сесии обикновено приключват за под секунда.

Single Request

POST /api/single/

Изпраща HTTP заявка с реалистични мрежови характеристики, подобни на браузър, без да стартира реален браузър. Това е най-бързият endpoint.

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`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`, за да изпратите обикновен клиентски сигнатура.
`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	DNS кеш TTL в секунди (макс.: 240)
`followRedirects`	number	Не	disabled	Максимален брой пренасочвания за следване (0-20). Пропуснете за деактивиране.
`tryJsonData`	boolean	Не	false	Анализиране на тялото на отговора като JSON, ако е възможно
`returnBuffer`	boolean	Не	false	Връщане на суров буфер вместо декодиран низ
`data`	any	Не	-	Тяло на заявката (string или object, автоматично сериализирано в JSON)
`proxy`	string	Не	-	Proxy ID от предишен отговор, за фиксиране на същата изходна точка. Предайте обратно непрозрачния низ буквално. Суров прокси адрес се отхвърля с `400 Invalid proxy format`. Някои ID не могат да бъдат фиксирани: вижте Pinning an exit.
`browser`	string	Не	Chrome	Браузър за представяне: Chrome, Edge, Safari, Firefox или Tor. Вижте Browser profiles.
`os`	string	Не	-	Операционна система за представяне: Windows, macOS, Android или iOS. Име на фамилия приема всяка от нейните версии.
`version`	string	Не	newest	Версия на браузъра за представяне, както е посочена в каталога. Най-новото съвпадение печели, когато съвпадат няколко.
`profile`	string	Не	-	Точно id на профил от `GET /api/profiles` вместо трите полета по-горе.
`validate`	object	Не	-	Правила за валидиране на отговора (вижте по-долу)

Browser profiles

По подразбиране заявката представя най-новия Google Chrome. Някои цели приемат един браузър и отказват друг, така че browser, os и version стесняват каталога от измерени профили, а profile избира такъв по id.

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

Правила:

Изборът изисква unblocker (включен по подразбиране). При изключен unblocker не се изпращат browser headers, така че заявката се отхвърля, вместо да бъде приложена наполовина.
Когато съвпадат няколко профила, се избира най-новата версия.
Комбинация, която каталогът не може да предостави, връща грешка с посочване на наличните опции. Заявката никога не се изпраща като различен браузър.
Същите четири полета са достъпни в обекта request на POST /proxy/.

GET /api/profiles връща пълния каталог и не изисква API key:

{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}

osFamily е стойността, по която да се филтрира при изграждане на селектор; os запазва името на рилийза за показване.

Validation Rules

Обектът 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	Двойки ключ-стойност за header, които трябва да присъстват
`validate.headers.fail`	object	Двойки ключ-стойност за header, които предизвикват грешка
`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,
  "proxy": "A1B2C3"
}

Когато целта изпълнява проверка за ботове преди зареждане на съдържанието, отговорът съдържа и обект 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 Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`request`	object	Да	-	Единично тяло на заявка (същите полета като Single Request по-горе)
`timeout_ms`	number	Не	45000	Общо време за изчакване (timeout) за всички опити в ms (макс: 120000)
`maxTries`	number	Не	5	Максимален брой опити за ротация на проксита (макс: 90)
`ignoreProxies`	string[]	Не	-	Прокси ID-та за изключване от ротацията (използвайте ID-та, върнати от предишни отговори)
`exitCountries`	string[]	Не	-	Стриктен бял списък от двубуквени кодове на държави, видими за целта (напр. `["CZ", "GB"]`). Стойностите се изчистват от интервали, преобразуват се в главни букви и се дедупликират. Проксита с неизвестни изходни точки се изключват и заявката никога не преминава към незаявена държава.
`exitClass`	string	Не	-	`standard` или `premium`. `premium` позволява на заявката да ескалира до премиум изходна точка, когато стандартният пул се затруднява със защитена цел. Изисква план, който включва премиум изходни точки.

Обхват на exitCountries

Изборът използва най-новите налични метаданни за държава, видима за целта, които обикновено се обновяват на около десет минути. Това не е географско търсене на живо по време на заявката. Не определяйте обслужващата държава въз основа на хост адреса на проксито.

Ако текущият пул няма съвпадение за заявените държави, отговорът връща HTTP 200 с обвивка за грешка:

{
  "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"
    }
  }'

Отговор:

{
  "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	Кодиран идентификатор на използваното proxy. Използвайте го повторно в Single или Browser request, като го подадете в полето `proxy`, или го пропуснете при следващия Proxy request чрез `ignoreProxies`.
`exitCountry`	string	Двубуквен код на държавата, видим за целта, на proxy сървъра, обслужил заявката. Наличен е само когато в заявката е зададен `exitCountries`. Винаги проверявайте дали е един от заявените кодове, преди да се доверите на отговора.
`exitClass`	string	Класът изходна точка, обслужил тази заявка, наличен при успешен отговор, когато заявката е посочила такъв. `premium` означава, че premium изходна точка е върнала тялото; `standard` означава, че е използван стандартният пул. Неуспешното извикване не връща съдържание, така че не съдържа `exitClass`; проверете неговия `attemptReport` за резултата от опитите.
`total`	number	Общо астрономическо времетраене в секунди (float). Включва избор на proxy, повторни опити и успешния опит. `total_time` е само за вътрешния request; `total` винаги е >= `total_time`.
`profile`	string	Профилът на браузъра, избран от ротацията, наличен само когато не съвпада с първоначално заявения. Липсата му означава, че заявката е изпратена точно както е описана. Подайте обратно id като `profile` при следващи извиквания, за да запазите работещия браузър.
`error`	string	Съобщение за грешка при неуспешна заявка. При несъответствие на scope стойността на `code` е `no_eligible_proxy`, а `details.exitCountries` връща нормализирания scope.
`attemptReport`	object	Наличен при всяко неуспешно Proxy извикване. Отчита какво са срещнали опитите, така че блокиран пул, неактивен пул и правило `validate` без съвпадение да не изглеждат като една и съща грешка. Вижте по-долу.

Всички полета от отговора на Single Request също са включени, включително defense: опит през proxy, срещнал проверка за ботове, я отчита по същия начин както 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	Точката за изход не отговори, така че сайтът изобщо не беше достигнат
`defense`	integer	Сайтът отговори и в този отговор беше разпозната проверка за ботове
`contentRejected`	integer	HTTP 200, без проверка за ботове, отхвърлен единствено от вашия `validate.data`
`statusRejected`	integer	Сайтът отговори, без проверка за ботове, отхвърлен от вашия `validate.status`
`other`	integer	Получен е отговор, като нито едно от горните не е приложимо
`vendors`	string[]	Доставчици на проверки за ботове, разпознати където и да е в задачата
`profilesTried`	string[]	Браузърни профили, изпратени от задачата, по ред на първо използване. `default` означава, че вашата request е изпратена непроменена.
`summary`	string	Едно изречение, съставено от броячите, безопасно за логване

Стрингът error остава непроменен, така че клиент, който го обработва, продължава да работи. Какво да направите за всяко от преброяванията: Защо proxy request изчерпа опитите.

exitClass

Някои целеви сайтове отхвърлят изходните точки от стандартния пул, независимо колко опита се направят. exitClass: premium указва на Proxy, че може да ескалира такава request до premium exit в допълнение към стандартния пул, вместо само да ротира в рамките на него.

{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}

Три неща си струва да знаете, преди да го изпратите.

Това е позволение, а не инструкция. Стандартният pool все още се състезава за отговора и обикновено печели. Premium exit се включва само когато pool-ът е изразходвал кратък лимит за заявката или целта видимо я е отказала. Заявка, на която стандартният pool отговори преди изпробването на premium exit, е нормален успех и не ви струва premium трафик. След като premium exit бъде изпробван, неговият трафик се отчита, както е описано по-долу.

Отговорът ви показва какво реално ви е обслужило. Когато посочите клас, response връща exitClass:

{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}

premium означава, че premium exit е върнал тялото. standard означава, че стандартният pool го е върнал, което е отговорът, който получавате и когато не може да бъде получен premium exit, както и когато включеният във вашия план premium трафик (плюс всичко допълнително закупено) е изчерпан за отчетния период. Нито едно от двете не е грешка и можете да засичате вашия premium трафик спрямо тях за всяка заявка, вместо спрямо месечна стойност. Същата стойност се предава в response header-а X-FourA-Exit-Class (вижте Response Headers).

Premium трафикът се измерва в мрежата. Premium опитът отчита това, което е изпратил и получил при преминаването през мрежата, компресирано и криптирано в процеса, независимо дали е върнал вашата страница. Опит, който все още се изпълнява, когато друг exit е отговорил, се прекратява незабавно и не се отчита. Premium трафикът се брои към вашия premium лимит, както и в рамките на общия ви bandwidth: същите байтове, отчетени два пъти, без никога да се сумират. Когато premium exit е доставил страницата, неговият трафик представлява целият трафик на заявката, така че страницата не се брои повторно като стандартен трафик. Вашата страница Usage & Limits показва общия трафик, premium частта от него и premium лимита, спрямо който се измерва потреблението ви.

Пропускането на полето не е същото като изпращането на standard. Пропускането му оставя решението неопределено; изпращането на standard изрично указва, че тази заявка никога не трябва да ескалира, което е начинът да предпазите конкретна задача от използване на premium трафик.

Изчерпването не е грешка. Заявка, посочваща premium след изчерпване на лимита, продължава да работи: стандартният pool я обслужва и отговорът съдържа standard. Нито една задача не спира поради изчерпан лимит.

exitClass: premium изисква план, който включва premium exits. При план без такива заявката никога не изразходва premium exit: тя или се отхвърля с 403, съдържащ X-FourA-Limit: plan_limit_premium (вижте Rate Limits), или се обслужва от стандартния pool с exitClass: standard в отговора. Обработвайте и двата случая.

Browser Profile Rotation

Proxy ротира exits. Когато даден сайт откаже браузъра, представен от FourA, а не самия exit, от който идва, Proxy преминава към друга browser фамилия от каталога. Това не добавя нов опит: ротацията променя какво изпраща повторният опит, но никога не определя дали да има такъв.

Proxy също така запомня временно фамилията, която сайтът последно е приел, така че следващо извикване към същия сайт може да започне с тази фамилия вместо с тази по подразбиране. Отговорът я посочва в profile, както прави за всяка фамилия, избрана от ротацията.

Изрично зададен profile, browser, os или version във вашия вътрешен request никога не се презаписва, както и заявка, която носи собствен User-Agent или Cookie header, тъй като разрешението е обвързано с подписа, чрез който е получено.

Browser Request

POST /api/browser/

Отваря вашия URL в Chrome инстанция. Страницата се зарежда, JavaScript се изпълнява и получавате напълно рендирания HTML заедно със списъка с cookie.

Request Body

Параметър	Тип	Задължителен	По подразбиране	Описание
`url`	string	Да	-	Целеви URL
`headers`	object	Не	-	Персонализирани header елементи като двойки ключ-стойност
`cookies`	array	Не	-	Cookie за задаване: `[{name, value, domain?}]`
`userAgent`	string	Не	-	Персонализиран User-Agent низ
`unblocker`	boolean	Не	`true`	Изпълнява проверката, която страницата изисква преди зареждане (страница с проверка или подобна защита). Включено по подразбиране. Задайте `false`, за да рендирате точно това, което страницата връща, включително страница с проверка.
`proxy`	string	Не	-	Proxy ID от предишен response за запазване на същата изходна точка. Предайте непроменения низ обратно. Директен proxy адрес се отхвърля с `400 Invalid proxy format`.
`exitCountry`	string	Не	-	Двубуквен код на държава (ISO 3166-1 alpha-2), от която излиза заявката. Настройва часовника на браузъра към съответстващата часова зона. Вижте Matching the browser clock to the exit.
`timeout_ms`	number	Не	30000	Таймаут за зареждане на страницата в ms (макс: 120000)
`checkStatus`	number	Не	-	Очакван HTTP статус (заявката се проваля при различен статус)
`checkText`	string	Не	-	Текст, който задължително трябва да присъства в рендираната страница

Matching the browser clock to the exit

Дадена страница може да прочете часовата зона на браузъра и да я сравни с държавата на IP адреса, който вижда. Несъответствието е един от най-лесните сигнали за bot detector, а премахването му не ви струва нищо.

Задайте exitCountry на държавата, през която излиза вашият трафик, и браузърът ще подаде принадлежаща към нея часова зона:

{
  "url": "https://example.com",
  "proxy": "A1B2C3",
  "exitCountry": "BR"
}

Правила:

Стойността е изходната държава, тоест държавата, която целта вижда, а не където се хоства проксито. Двете се различават достатъчно често, за да има значение.
Пропуснете го и FourA ще използва изходната държава, когато знае такава, а в противен случай ще остави часовника на браузъра непокътнат, вместо да отгатва.
Код на държава, който FourA не разпознава, се третира по същия начин като пропускане на полето. Това не е грешка.
Само часовникът следва държавата. Accept-Language и съдържанието, което сайтът предоставя, остават непокътнати, така че дадена страница няма да смени езика си неочаквано.

Параметърът `userAgent`

Изпратете userAgent и точно този низ ще бъде видян от страницата, нейните уеб работници и целта. FourA също извежда съответстващите client hints от него (sec-ch-ua, sec-ch-ua-platform, navigator.platform, както и стойностите с висока ентропия, които даден детектор изисква по име), така че заявката да не твърди един браузър в хедъра и друг в JavaScript.

userAgent в отговора е този, който е бил представен. Това има значение, когато възпроизвеждате clearance: бисквитката cf_clearance е обвързана с изхода и User-Agent, който я е заслужил, така че върнете низа, който отговорът е отчел, а не този, който мислите, че е бил използван. Вижте Проверки на сайта.

Изпратете низ, който не е на Chromium (например Firefox User-Agent), и той ще бъде представен както е, без прикрепен списък с марки на 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"]},
  "proxy": "A1B2C3"
}

Поле	Тип	Описание
`status`	number	HTTP статус код от целевия сайт
`headers`	object	Response хедъри
`body`	string or object	Напълно рендерирано съдържание на страницата. HTML като string при 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`, ако е била засечена бот защита и тя е била успешно премината при това извикване. Липсва в противен случай. Определя дали заявката струва 5 или 10 кредита.
`defenses`	object	`present` изброява всички доставчици, разпознати по време на зареждането на страницата, а `cleared` изброява тези, чието преминаване крайната страница съдържа. Даден доставчик може да се появи в `present` и никога в `cleared`. Вижте Site checks.
`proxy`	string	Кодирано ID на проксито, през което е минала заявката (само когато в заявката е подаден `proxy`). Използвайте го повторно при следващи извиквания, за да запазите същата изходна точка.
`error`	string	Съобщение за грешка, ако заявката е неуспешна

Фиксиране на изходна точка (Exit Pinning)

Стойност proxy при Single или Browser заявка фиксира изходната точка, използвана от предишно извикване. Върнете непрозрачното ID точно както е получено, никога реален прокси адрес.

Три стойности се отхвърлят, всички с код 400:

Грешка	Значение
`Invalid proxy format`	Стойността не е ID, издадено от FourA. Суров прокси адрес попада тук.
`Proxy not found`	ID-то е декодирано, но вече не съответства на активна изходна точка. Вземете ново 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` за целевия response)
400	Невалидно тяло на request, параметри, целеви IP в частен/резервиран диапазон или proxy ID, което не може да бъде фиксирано
401	Липсващ или невалиден API key
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 се свърза с двигателя си, но отговорът беше неизползваем. Опитайте отново.
503	Услугата е временно деактивирана или претоварена, или `Backend service unavailable` докато двигателят се рестартира
504	`Upstream timeout`. Двигателят не приключи в рамките на предвиденото време за тази заявка. Увеличете `timeout_ms` или опитайте отново.

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

Smart Fetch (Auto): Кога да оставите FourA да избере пътя вместо вас
Избор на правилния endpoint: Кога да изберете ръчно Single, Proxy или Browser
Автентикация: Управление на вашите API keys
Обработка на грешки: Ефективно обработване на грешки
Проверки на сайтове: Прочетете полето defense и приложете clearance отново
Защо proxy заявката изчерпа опитите си: Прочетете attemptReport и реагирайте според него
Rate Limits: Запознайте се с лимитите за заявки
Бърз старт: Вашата първа заявка за 30 секунди

Обновено: 30 септември 2026 г.

Справочник за API Endpoints

Base URL

Автентикация

Response Headers

Endpoints

Ограничения за целеви URL

Smart Fetch (Auto)

Request Body

Response

Пример

Бележки

Single Request

Request Body

Browser profiles

Validation Rules

Пример

Proxy Request

Request Body

Обхват на exitCountries

Пример

Защо се провали Proxy извикването

exitClass

Browser Profile Rotation

Browser Request

Request Body

Matching the browser clock to the exit

Параметърът userAgent

Пример

Фиксиране на изходна точка (Exit Pinning)

HTTP статус кодове

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

Параметърът `userAgent`