Dokumentacja endpointów API

Dokumentacja referencyjna wszystkich endpointów FourA API z parametrami requestów i formatami response.

Bazowy URL

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

Uwierzytelnianie

Każde request wymaga Twojego klucza API w headerze 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"}'

Twórz klucze API i zarządzaj nimi w Dashboardzie. Klucze używają prefiksu pk_live_.

Nagłówki odpowiedzi

Odpowiedzi z /api/* zawierają dwa nagłówki korelacji:

Nagłówek Wartość Opis
X-FourA-Request-Id UUID Unikalny identyfikator przypisany do żądania. Zwracany w każdej odpowiedzi, w tym 4xx i 5xx, z wyjątkiem treści, których FourA nie może w ogóle odczytać: 400 Invalid JSON in request body i 413 są odrzucane przed przypisaniem identyfikatora. Zapisuj go w logach po swojej stronie.
X-FourA-Credits integer Kredyty wykorzystane na to żądanie. Zwracany w każdej odpowiedzi, która dotarła do silnika, zarówno zakończonej sukcesem, jak i niepowodzeniem (praca została wykonana w obu przypadkach). Wywołanie, które FourA odrzuci przed uruchomieniem silnika (brakujący lub nieprawidłowy klucz, limit planu lub platformy, odrzucony cel lub proxy ID), nie zawiera tej wartości. Zobacz Wyniki żądań, aby sprawdzić, które wyniki podlegają rozliczeniu.

Ten sam identyfikator żądania indeksuje podgląd payloadu żądania i odpowiedzi w sekcji Dashboardu Activity Log (przechowywane przez 24 godziny, ostatnie 200 na klucz), dzięki czemu możesz sprawdzić dokładne żądanie później i odtworzyć je z poziomu Activity bezpośrednio w Playgroundzie. Dołącz go przy kontakcie z pomocą techniczną, aby zlokalizować żądanie w kilka sekund.

$ 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
...

Zobacz Response Headers, aby sprawdzić pełną listę i wskazówki dotyczące użycia.

Punkty końcowe

Korzystasz z tych punktów końcowych przez MCP? Serwer @fouradata/mcp udostępnia wszystkie cztery punkty końcowe jako natywne narzędzia MCP (foura_auto, foura_single, foura_proxy, foura_browser) z takimi samymi formatami danych wejściowych oraz opcją offload_large pozwalającą na oszczędzanie tokenów przy dużych odpowiedziach. Różnice: foura_browser nie ma pola lean, a foura_proxy nie obsługuje jeszcze pól exit location.

FourA oferuje cztery punkty końcowe zapytań, każdy zoptymalizowany pod kątem innego scenariusza:

Punkt końcowy Najlepszy do
POST /auto/ Inteligentne pobieranie. Podajesz URL, a FourA wybiera najtańszą działającą ścieżkę (rotowane proxy lub przeglądarkę oraz bezpośrednie zapytanie z forceProxy: false) i zapamiętuje, co działa dla danego hosta.
POST /single/ Szybkie zapytania HTTP, strony statyczne, interfejsy API
POST /proxy/ Chronione witryny z automatyczną rotacją proxy, opcjonalny wybór kraju widocznego dla celu
POST /browser/ Strony renderowane przez JavaScript, SPA
GET /profiles Katalog profili przeglądarek dla single i proxy. Publiczny, bez klucza API.

Więcej szczegółów na temat wyboru odpowiedniego rozwiązania znajdziesz w sekcjach Choosing the Right Endpoint oraz w przewodniku Smart Fetch guide.

Ograniczenia docelowych adresów URL

Cele wskazujące na prywatne, pętli zwrotnej lub zastrzeżone pule adresów IP (RFC 5735, RFC 6598, zastrzeżone bloki IPv6) są odrzucane z kodem 400, zanim zapytanie opuści FourA. Przekazywane są wyłącznie publiczne nazwy hostów i adresy 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." }

Cel wskazujący na własny host API FourA (eu.api.foura.ai lub api.foura.ai) jest również odrzucany z kodem 400 na wszystkich czterech endpointach, zanim cokolwiek zostanie pobrane lub naliczone. Adres URL zawierający spację lub znak sterujący jest odrzucany z kodem 400 w trybach Single, Proxy oraz Auto w ten sam sposób; zakoduj spację jako %20 (Browser pobiera go tak, jak Chrome). Jedyną stroną pobieraną tam przez FourA jest /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 (Auto)

POST /api/auto/

Przekazujesz URL oraz opcjonalne reguły validate. FourA przechodzi przez zoptymalizowaną pod kątem kosztów ścieżkę (rotowany proxy, następnie pełna przeglądarka) i zatrzymuje się na pierwszym poziomie, który zwróci response zaakceptowany przez Twoje reguły. Przy forceProxy: false najpierw wykonywana jest tania próba bezpośrednia. Przy kolejnych wywołaniach do tego samego hosta odtwarzana jest rozgrzana sesja, dzięki czemu drugie trafienie jest tanie.

Nie musisz konfigurować ponownych prób, rozmiarów pul ani liczby proxy. FourA uczy się ich dla każdego hosta.

Request Body

Parametr Typ Wymagany Domyślnie Opis
url string Tak - Docelowy URL
method string Nie "GET" Metoda HTTP
headers [string, string][] Nie - Nagłówki do wysłania do celu jako pary [name, value]. Wysyła je każdy poziom z wyjątkiem poziomu przeglądarki. Wysłany Cookie trafia do witryny bez zmian, a pliki cookie z zapisanej sesji są dodawane obok niego wyłącznie pod nazwami, których nie przesłano. userAgent z zapisanej sesji zastępuje Twój User-Agent. Poziom proxy pomija nagłówki warunkowe, takie jak If-None-Match, chyba że Twój validate.status.accept zawiera 304.
data any Nie - Treść request dla metod innych niż GET
validate object Nie - Kryteria sukcesu, o takiej samej strukturze jak validate w Single Request (patrz poniżej). Określ dla trybu auto, jak wygląda właściwa strona, aby odróżnić treść od strony z wyzwaniem.
returnSession boolean Nie true Dołącz zwycięską sesję (proxy, cookies, userAgent) do response, aby umożliwić jej ponowne użycie przez /api/single/ lub /api/browser/.
forceProxy boolean Nie true Zawsze kieruj ruch przez rotowany proxy. Ustaw false, aby zezwolić na tańszą ścieżkę bezpośrednią, gdy cel na to pozwala (niektóre mechanizmy obronne są bardziej rygorystyczne wobec ruchu z proxy).
timeout_ms integer Nie 120000 Całkowity budżet czasowy na całe wywołanie w milisekundach. Wszystkie próby cząstkowe mieszczą się w tym budżecie. Min. 5000, maks. 180000.
ignoreProxies string[] Nie - Identyfikatory proxy do pominięcia przy każdej próbie cząstkowej. Użyj identyfikatorów zwróconych przez wcześniejsze response /api/auto/ lub /api/proxy/.
followRedirects integer Nie 5 Maksymalna liczba przekierowań do obsłużenia na niższych poziomach ścieżki. 0 wyłącza przekierowania. Maks. 20.
exitClass string Nie - standard lub premium, tak jak w Proxy Request. premium pozwala eskalować wywołanie do węzła premium, gdy standardowa pula nie może uzyskać dostępu do strony. Wymaga planu zawierającego węzły premium. Zobacz exitClass w Smart Fetch.

Response

{
  "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..."
  }
}
Pole Typ Opis
status number Status HTTP z celu.
data string Ciało response jako tekst, niezależnie od poziomu drabiny, który je obsłużył. Strona JSON wraca jako tekst JSON, więc parsujesz ją samodzielnie.
headers array or object Nagłówki response z celu. Poziomy pojedyncze i proxy zwracają tablicę obiektów nagłówków dla każdego przeskoku; poziomy przeglądarkowe zwracają płaski obiekt.
meta.rung string Który poziom drabiny dostarczył response. Jeden z: probe (tani request bezpośredni, tylko z forceProxy: false), proxy (rotujące proxy), browser (pełne renderowanie w przeglądarce), cache (odtworzona rozgrzana sesja), warmup (strona wejściowa witryny została pobrana jako pierwsza, a jej cookie otworzyły głęboki URL) lub fail (żaden poziom nie wygenerował zaakceptowanego response).
meta.solved boolean Czy strona wymagała dodatkowego kroku (strony wyzwania / challenge) i został on ukończony podczas tego wywołania.
meta.attempts number Podpróby wykonane przed sukcesem.
meta.credits number Łączna liczba kredytów zużytych na to wywołanie. Odpowiada X-FourA-Credits.
meta.attemptsByEngine object Requesty wysłane do single, proxy i browser. Request przeglądarkowy odrzucony przez Twój plan wlicza się, ponieważ został wysłany.
meta.browserRequests number Requesty przeglądarkowe, które zajęły slot z Twojego dziennego limitu. Request przeglądarkowy odrzucony przez Twój plan nie zużywa nic.
meta.exitClass string Jaka klasa wyjścia dostarczyła odpowiedź, obecne gdy request określał exitClass: premium lub standard. Ta sama wartość jest przesyłana w nagłówku response X-FourA-Exit-Class.
session.proxy string Zakodowany ID proxy, które dostarczyło response. Użyj go ponownie w requeście Single lub Browser. Obecne, gdy returnSession to true.
session.cookies array Cookie do odtworzenia, każde zawierające co najmniej name i value. Poziom przeglądarkowy zwraca cookie jar przeglądarki. Poziom proxy lub bezpośrednia próba zwraca tylko te cookie, które otworzyły stronę (np. ustawione przez stronę weryfikacyjną witryny), a nie wszystkie cookie ustawione przez stronę, więc lista może być pusta. Obecne, gdy returnSession to true.
session.userAgent string User-Agent użyty podczas udanej próby. Obecne, gdy returnSession to true.
error string Komunikat błędu, jeśli wywołanie się nie powiodło.
attemptReport object Przy nieudanym wywołaniu: requesty silnika, które wróciły bez strony, pogrupowane według przyczyny. Zobacz Smart Fetch.

Przykład

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

Uwagi

  • Auto działa jako koordynator. Wywołuje wewnętrznie Single, Proxy lub Browser i przekazuje Twój klucz API do każdego podwywołania. Wywołanie Auto to jedno żądanie w Twoim Activity Log oraz w Overview, z sumą kredytów jego podwywołań; podwywołania są wymienione pod nim jako próby i nigdy nie liczą się jako osobne żądania.
  • Przekaż validate.data.accept z podciągiem znaków, który zawiera tylko prawdziwa strona. Bez tego auto nie odróżni prawdziwego 200 od strony z wyzwaniem zwróconej ze statusem 200.
  • Usunięta strona jest odpowiedzią witryny, a nie odmową. Gdy dwa węzły wyjściowe zwrócą ten sam kod 404 lub 410, a Twoja validate go nie akceptuje, wywołanie kończy się tym statusem status i nagłówkiem error rozpoczynającym się od the site answered. Podaj ten status w validate.status.accept, a Auto zwróci pierwszą odpowiedź z tym statusem, która spełnia pozostałe warunki Twojej validate. To samo dotyczy każdego innego podanego tam statusu, z wyjątkiem 403, 429, 503 i 202, które witryny wysyłają również ze stroną wyzwania.
  • timeout_ms ogranicza całe wywołanie. Pierwsze, zimne wywołanie chronionej witryny może zająć kilkadziesiąt sekund; ponownie użyte, rozgrzane sesje kończą się zwykle w czasie poniżej sekundy.

exitClass w Smart Fetch

exitClass działa w Smart Fetch tak samo jak w Proxy Request: jako zezwolenie, a nie polecenie. Auto najpierw próbuje standardowej puli. Gdy standardowa pula nie może dotrzeć do strony, a żądanie wskazuje premium, Auto otwiera stronę w przeglądarce przez węzeł wyjściowy premium. Utworzona w ten sposób sesja obsługuje Twoje późniejsze wywołania do tej samej witryny, które również wskazują premium; wywołania, które go nie wskazują, nigdy z niej nie korzystają.

Wyczerpanie limitu nie jest błędem. Gdy ruch premium w Twoim planie zostanie wyczerpany w danym okresie rozliczeniowym, wywołanie jest kontynuowane w standardowej puli, a meta.exitClass zwraca standard. W planie bez węzłów wyjściowych premium wywołanie wysyłające exitClass: premium jest odrzucane z kodem 403 zawierającym X-FourA-Limit: plan_limit_premium, zanim zostanie wykonana jakakolwiek praca.

Ruch premium jest mierzony tak samo jak w Proxy Request. Strona otwarta w przeglądarce ładuje więcej niż samą stronę, dlatego strona premium Smart Fetch zużywa więcej ruchu premium niż ta sama strona pobrana przez Proxy Request. Aby to ograniczyć, strona premium Smart Fetch ładuje się bez obrazów, czcionek i multimediów oraz bez skryptów od znanych dostawców reklam, analityki i zgód.


Single Request

POST /api/single/

Wysyła żądanie HTTP z realistycznymi, zbliżonymi do przeglądarki charakterystykami sieciowymi, bez uruchamiania prawdziwej przeglądarki. To najszybszy endpoint.

Request Body

Parametr Typ Wymagany Domyślnie Opis
method string Tak - Metoda HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
url string Tak - Docelowy URL. Użyj {ts} w dowolnym miejscu adresu URL, aby wstawić bieżący znacznik czasu w celu ominięcia pamięci podręcznej.
headers [string, string][] Nie - Niestandardowe nagłówki jako pary [nazwa, wartość]
unblocker boolean Nie true Wysyłaj realistyczne nagłówki przeglądarki (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Domyślnie włączone. Ustaw false, a FourA nie doda żadnych nagłówków przeglądarki, tylko te przekazane przez Ciebie.
timeout_ms number Nie 15000 Całkowity limit czasu w ms (maks.: 120000)
connect_timeout_ms number Nie 5000 Limit czasu połączenia w ms
accept_timeout_ms number Nie 5000 Limit czasu akceptacji w ms (czas oczekiwania na zaakceptowanie połączenia)
server_response_timeout_ms number Nie 15000 Limit czasu odpowiedzi serwera w ms (czas oczekiwania na pierwszy bajt)
dns_cache_timeout_sec number Nie 120 TTL pamięci podręcznej DNS w sekundach (maks.: 240)
followRedirects number Nie wyłączone Maksymalna liczba przekierowań do wykonania (0-20). Pomiń, aby wyłączyć.
tryJsonData boolean Nie false Parsuj treść odpowiedzi jako JSON, jeśli to możliwe
returnBuffer boolean Nie false Zwróć surowy bufor zamiast zdekodowanego ciągu znaków
data any Nie - Treść żądania (ciąg znaków lub obiekt, automatycznie serializowany do JSON)
proxy string Nie - Identyfikator proxy z wcześniejszej odpowiedzi, aby przypiąć ten sam węzeł wyjściowy. Przekaż nieprzezroczysty ciąg znaków dosłownie. Surowy adres proxy jest odrzucany z błędem 400 Invalid proxy format. Niektórych identyfikatorów nie można przypiąć: zobacz Pinning an exit.
browser string Nie Chrome Przeglądarka do symulacji: Chrome, Edge, Safari, Firefox lub Tor. Zobacz Browser profiles.
os string Nie - System operacyjny do symulacji: Windows, macOS, Android lub iOS. Nazwa rodziny akceptuje dowolną z jej wersji.
version string Nie newest Wersja przeglądarki do symulacji, zgodnie z katalogiem. W przypadku wielu pasujących wersji wybierana jest najnowsza.
profile string Nie - Dokładny identyfikator profilu z GET /api/profiles, zamiast trzech powyższych pól.
validate object Nie - Reguły walidacji odpowiedzi (patrz poniżej)

Profile przeglądarek

Domyślnie żądanie symuluje najnowszą wersję Google Chrome. Niektóre cele akceptują jedną przeglądarkę, a odrzucają inną, dlatego browser, os i version zawężają katalog zmierzonych profili, a profile wybiera profil według identyfikatora.

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

Zasady:

  • Wybór wymaga unblocker (domyślnie włączone). Przy wyłączonym unblocker nagłówki przeglądarki nie są wysyłane, więc request jest odrzucany zamiast częściowo zastosowany.
  • Gdy pasuje kilka profili, wybierana jest najnowsza wersja.
  • Kombinacja niedostępna w katalogu zwraca błąd ze wskazaniem dostępnych opcji, a nieznany identyfikator profile zwraca unknown profile '<id>'. Request nigdy nie jest wysyłany jako inna przeglądarka.
  • Te same cztery pola są dostępne wewnątrz obiektu request w POST /proxy/.

GET /api/profiles zwraca pełny katalog i nie wymaga klucza API:

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

osFamily to wartość używana do filtrowania podczas tworzenia selektora; os zachowuje nazwę wydania do wyświetlenia.

Reguły walidacji

Obiekt validate pozwala zdefiniować warunki sukcesu i błędu. Jeśli warunek fail zostanie spełniony, żądanie jest traktowane jako nieudane. Jeśli warunki accept są ustawione, tylko pasujące odpowiedzi są traktowane jako udane.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
Pole Typ Opis
validate.status.accept number[] Kody statusu HTTP do zaakceptowania
validate.status.fail number[] Kody statusu HTTP do odrzucenia
validate.headers.accept object Odpowiedź jest poprawna, gdy co najmniej jedna para pasuje na dowolnym etapie przekierowania. Nazwy i wartości są dopasowywane bez uwzględniania wielkości liter, na podstawie fragmentu tekstu.
validate.headers.fail object Pary klucz-wartość nagłówka, które powodują niepowodzenie
validate.data.accept string[] Odpowiedź jest poprawna, gdy treść zawiera co najmniej jeden z tych ciągów znaków
validate.data.fail string[] Ciągi znaków w treści odpowiedzi, które powodują niepowodzenie

Przykład

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
}

Gdy cel uruchamia weryfikację bota przed zwróceniem treści, response zawiera również obiekt defense ze wskazaniem dostawcy oraz informacją, czy weryfikacja zakończyła się powodzeniem:

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
Pole Typ Opis
status number Kod statusu HTTP z serwera docelowego
headers array Jeden obiekt na każdy przeskok przekierowania. Każdy zawiera pole result z linią statusu oraz wszystkimi nagłówkami odpowiedzi. Nagłówki wielowartościowe (Set-Cookie, Link, WWW-Authenticate) są zwracane jako tablice ciągów znaków.
data string/object Ciało odpowiedzi (JSON, jeśli tryJsonData ma wartość true)
total_time number Całkowity czas żądania w sekundach
proxy string Zakodowany identyfikator proxy, przez który przeszło żądanie (tylko wtedy, gdy w żądaniu podano proxy). Użyj go ponownie w kolejnym wywołaniu, aby przypiąć ten sam węzeł wyjściowy.
defense object Obecne, gdy cel wykonał weryfikację bota dla tego żądania lub gdy ponowna próba z własnymi plikami cookie witryny zwróciła treść. defense.solved wskazuje, czy weryfikacja zakończyła się sukcesem, a defense.retry określa, czy ponowienie dostarczyło zawartość. Zobacz Weryfikacje witryny, aby poznać wszystkie pola i pełną listę systemów.
error string Komunikat o błędzie w przypadku niepowodzenia żądania

Żądanie proxy

POST /api/proxy/

Kieruje Twoje żądanie przez rotacyjne proxy z automatycznym ponawianiem w przypadku błędu. Opcjonalnie zawęża wybór do zestawu krajów wyjściowych widocznych dla celu.

Ciało żądania

Parametr Typ Wymagany Domyślnie Opis
request object Tak - Pojedynczy request body (te same pola co w Single Request powyżej)
timeout_ms number Nie 45000 Całkowity timeout dla wszystkich prób w ms (maksymalnie: 120000)
maxTries number Nie 5 FourA przestaje uruchamiać nowe próby, gdy tyle z nich zakończy się niepowodzeniem (maksymalnie: 90). Próby działają równolegle, więc może zakończyć się ich nieco więcej niż ta liczba.
ignoreProxies string[] Nie - Identyfikatory proxy do wykluczenia z rotacji (użyj identyfikatorów zwróconych przez poprzednie odpowiedzi)
exitCountries string[] Nie - Ścisła lista dozwolonych dwuliterowych kodów krajów widocznych dla celu (np. ["CZ", "GB"]). Wartości są przycinane, zamieniane na wielkie litery i deduplikowane. Węzły wyjściowe z puli standardowej o nieznanym kraju są wykluczane, a pula standardowa nigdy nie przełącza się na niewskazany kraj. Węzeł wyjściowy premium również pochodzi z jednego z wymienionych krajów.
exitClass string Nie - standard lub premium. premium pozwala na eskalację żądania do węzła premium, gdy standardowa pula ma trudności z chronionym celem. Wymaga planu obejmującego węzły wyjściowe premium.
exitState string Nie - Region, z którego wychodzi połączenie. Wymaga exitClass: premium i dokładnie jednego kraju w exitCountries. Zobacz Exit location.
exitCity string Nie - Miasto, z którego wychodzi połączenie. Wymaga exitClass: premium i dokładnie jednego kraju w exitCountries.
exitAsn string Nie - Sieć, z której wychodzi połączenie, według numeru AS, na przykład 8866. Wymaga exitClass: premium i dokładnie jednego kraju w exitCountries.
exitOs string Nie - windows, android, ios lub mac: typ urządzenia, do którego należy adres. Wymaga exitClass: premium.
exitLifetimeMin integer Nie - Minuty, przez które węzeł wyjściowy zachowuje swój adres, od 3 do 1440. Wymaga exitClass: premium.

Zakres exitCountries

Wybór korzysta z najnowszych dostępnych metadanych o kraju widocznym dla celu, zwykle odświeżanych w ciągu około dziesięciu minut. Nie jest to geolokalizacja na żywo podczas wykonywania żądania. Nie należy wnioskować kraju obsługującego na podstawie adresu hosta proxy.

Jeśli bieżąca pula nie zawiera dopasowania dla żądanych krajów, a żądanie nie wskazywało exitClass: premium, odpowiedź zwraca HTTP 200 z kopertą błędu:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

Zachowaj żądany zakres i ponów próbę później. Zmień go lub rozszerz tylko wtedy, gdy wymagania dotyczące kraju w Twoim przepływie pracy wyraźnie się zmienią.

Przykład

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

Odpowiedź:

{
  "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
}
Pole Typ Opis
proxy string Zakodowany identyfikator użytego proxy. Użyj go ponownie w żądaniu Single lub Browser, przekazując go jako pole proxy, albo pomiń go w kolejnym żądaniu Proxy za pomocą ignoreProxies.
exitCountry string Dwuliterowy kod kraju proxy widoczny dla celu, które obsłużyło request. Występuje tylko wtedy, gdy w żądaniu ustawiono exitCountries, niezależnie od klasy węzła wyjściowego. Zawsze weryfikuj, czy jest to jeden z żądanych kodów, zanim uznasz odpowiedź za zaufaną.
exitClass string Klasa węzła wyjściowego, która obsłużyła ten request; pole obecne przy udanej odpowiedzi, gdy w żądaniu wskazano klasę. Wartość premium oznacza, że treść zwrócił węzeł premium; standard oznacza standardową pulę. Nieudane wywołanie niczego nie obsłużyło, więc nie zawiera exitClass; sprawdź jego pole attemptReport, aby dowiedzieć się, co napotkały próby.
total number Całkowity czas zegarowy w sekundach (float). Obejmuje wybór proxy, ponowienia oraz udaną próbę. total_time dotyczy tylko wewnętrznego requestu; total jest zawsze >= total_time.
profile string Profil przeglądarki wybrany przez rotację, obecny tylko wtedy, gdy nie był to profil żądany przez Ciebie. Brak pola oznacza, że request wyszedł dokładnie w podanej postaci. Przekaż ten id z powrotem jako profile w kolejnych wywołaniach, aby zachować działającą przeglądarkę.
error string Komunikat błędu, jeśli request się nie powiódł. Przy braku dopasowania zakresu (scope miss), code ma wartość no_eligible_proxy, a details.exitCountries zwraca znormalizowany scope.
attemptReport object Obecne przy każdym nieudanym wywołaniu Proxy. Zlicza przeszkody napotkane podczas prób, dzięki czemu zablokowana pula, martwa pula oraz reguła validate, która nigdy nie została dopasowana, nie wyglądają jak ten sam błąd. Zobacz poniżej.
request object Obecne przy nieudanym wywołaniu Proxy: request wykonany przez FourA, z uzupełnionymi wartościami domyślnymi oraz Twoimi ignoreProxies w przesłanej postaci.

Wszystkie pola odpowiedzi Single Request są również dołączone, w tym defense: próba proxy, która napotkała weryfikację bota, raportuje to w taki sam sposób jak Single.

Dlaczego wywołanie Proxy zakończyło się niepowodzeniem

Download maxTry limit reached ma taką samą postać niezależnie od przebiegu prób, dlatego każda nieudana odpowiedź Proxy zawiera attemptReport obok błędu:

{
  "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
}
Pole Typ Opis
total integer Liczba podjętych prób
noResponse integer Węzeł wyjściowy nie odpowiedział, więc połączenie ze stroną nie zostało nawiązane
defense integer Strona odpowiedziała i w tej odpowiedzi wykryto weryfikację botów
contentRejected integer HTTP 200, brak weryfikacji botów, odrzucone wyłącznie przez Twój validate.data
statusRejected integer Strona odpowiedziała, brak weryfikacji botów, odrzucone przez Twój validate.status
other integer Uzyskano odpowiedź i żaden z powyższych przypadków nie miał miejsca
vendors string[] Dostawcy weryfikacji botów wykryci w dowolnym momencie zadania
profilesTried string[] Profile przeglądarek wysłane przez zadanie, w kolejności pierwszego użycia. default oznacza, że request został wysłany bez zmian.
summary string Jedno zdanie zbudowane na podstawie liczników, bezpieczne do logowania

Ciąg error pozostaje niezmieniony, więc klient dopasowujący go nadal działa poprawnie. Co zrobić z poszczególnymi licznikami: Dlaczego proxy request wyczerpał limit prób.

exitClass

Niektóre cele odrzucają węzły wyjściowe ze standardowej puli bez względu na liczbę prób. exitClass: premium informuje Proxy, że może eskalować taki request do węzła wyjściowego premium poza standardową pulą, zamiast wyłącznie rotować w jej obrębie.

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

Warto wiedzieć o trzech kwestiach przed wysłaniem żądania.

To limit, a nie instrukcja. Pula standardowa nadal konkuruje o odpowiedź i zwykle wygrywa. Węzeł wyjściowy premium dołącza dopiero wtedy, gdy pula wyczerpie krótki limit czasu na żądanie lub cel wyraźnie je odrzuci. Żądanie obsłużone przez pulę standardową, zanim podjęto próbę z węzłem premium, jest zwykłym sukcesem i nie zużywa transferu premium. Gdy próba z węzłem premium zostanie podjęta, jego transfer jest naliczany zgodnie z poniższym opisem.

Węzeł wyjściowy premium pozostaje w ramach exitCountries. W przypadku listy krajów węzeł wyjściowy premium pochodzi z jednego z nich, a exitCountry w odpowiedzi wskazuje go tak samo, jak dla puli standardowej.

Odpowiedź informuje, co faktycznie obsłużyło żądanie. Po wskazaniu klasy odpowiedź zwraca exitClass:

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

premium oznacza, że treść została zwrócona przez węzeł wyjściowy premium. standard oznacza, że odpowiedź pochodzi ze standardowej puli, co ma miejsce także wtedy, gdy nie udało się uzyskać węzła premium oraz gdy limit transferu premium w ramach Twojego planu (wraz z dokupionym pakietem) został wyczerpany w danym okresie rozliczeniowym. Żadna z tych sytuacji nie jest błędem, a zużycie transferu premium możesz weryfikować na poziomie pojedynczego requestu zamiast sumy miesięcznej. Ta sama wartość jest przesyłana w nagłówku odpowiedzi X-FourA-Exit-Class (zobacz Response Headers).

Transfer premium jest mierzony na poziomie sieci. Próba z użyciem węzła premium zlicza dane wysłane i odebrane w sieci, z uwzględnieniem kompresji i szyfrowania, niezależnie od tego, czy strona została zwrócona. Próba, która wciąż trwała, gdy inny węzeł wyjściowy zwrócił odpowiedź, jest natychmiast przerywana, a przesłany do tego momentu ruch również jest wliczany. Transfer premium wlicza się do Twojego limitu premium oraz do całkowitego transferu: te same bajty są raportowane dwukrotnie, nigdy sumowane. Gdy strona została dostarczona przez węzeł premium, jego ruch stanowi całkowity ruch danego requestu, więc strona nie jest liczona ponownie jako ruch standardowy. Strona Usage & Limits pokazuje łączny transfer, jego część premium oraz limit premium, według którego następuje rozliczenie.

Pominięcie tego pola oraz przesłanie standard kierują request do standardowej puli: tylko premium zezwala na węzeł wyjściowy premium. Udany request określający klasę otrzymuje w odpowiedzi exitClass, a request pomijający to pole go nie ma.

Wyczerpanie limitu nie jest błędem. Request ze wskazaniem premium po wyczerpaniu limitu nadal działa: standardowa pula go obsługuje, a odpowiedź zwraca standard. Jedynym wyjątkiem jest request ze wskazaniem parametru exit location: standardowa pula nie może go obsłużyć, więc zostaje odrzucony.

exitClass: premium wymaga planu obejmującego węzły wyjściowe premium. W planie bez tej opcji request nigdy nie zużywa węzła premium: jest odrzucany ze statusem 403 i kodem X-FourA-Limit: plan_limit_premium (zobacz Rate Limits), zanim zostaną wykonane jakiekolwiek operacje.

Lokalizacja węzła wyjściowego

Węzeł wyjściowy premium może pochodzić z określonego miejsca w danym kraju i zachować swój adres tak długo, jak to potrzebne:

{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}

Odpowiedź zawiera nazwę węzła wyjściowego oraz kraj, z którego nastąpiło wyjście:

{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}

Ten identyfikator proxy zachowuje wszystko. Przekaż go do Single lub Browser, a żądanie wyjdzie z tego samego miejsca, bez żadnego innego pola obok. Zobacz Przypinanie węzła wyjściowego.

Zasady:

  • Użycie dowolnego z pól exitState, exitCity, exitAsn, exitOs lub exitLifetimeMin kieruje żądanie wyłącznie przez węzły wyjściowe premium. Standardowa pula nie podejmuje żadnej próby, ponieważ nie może ich obsłużyć.
  • Wymagają one pola exitClass: premium. Bez niego żądanie zostanie odrzucone z kodem 400 wskazującym brakujące pole.
  • Pola exitState, exitCity i exitAsn istnieją w ramach jednego kraju, dlatego wymagają dokładnie jednego kraju w exitCountries. Pola exitOs i exitLifetimeMin działają z wieloma: węzeł wyjściowy wybiera jeden z nich, a nagłówek exitCountry w odpowiedzi wskazuje, który wybrano.
  • Pola exitState, exitCity, exitAsn i exitOs wymagają planu z obsługą geotargetowania oraz węzłów wyjściowych premium.
  • W przypadku wyczerpania transferu premium żądanie jest odrzucane z kodem 403 i błędem X-FourA-Limit: plan_limit_premium, ponieważ pula standardowa nie może go zrealizować.
  • Jeśli żaden węzeł wyjściowy premium nie odpowiada dla danej lokalizacji, odpowiedź ma postać koperty błędu, takiej jak w sekcji Zakres exitCountries, z kodem błędu No premium exit answered for this request i polem code: no_eligible_proxy. Pole details.exitCountries pojawia się, gdy przesłano listę krajów.

Wartości są takie same, jakie port proxy przyjmuje dla state, city, asn i os.

Rotacja profili przeglądarki

Proxy rotuje węzły wyjściowe. Gdy strona odrzuca przeglądarkę przedstawioną przez FourA, a nie sam węzeł wyjściowy, Proxy przełącza się również na inną rodzinę przeglądarek z katalogu. Nie dodaje to kolejnej próby: rotacja zmienia parametry wysyłane w ramach ponowienia, a nie fakt jego wykonania.

Proxy zapamiętuje także przez pewien czas rodzinę przeglądarek ostatnio zaakceptowaną przez witrynę, dzięki czemu kolejne wywołanie do tej samej witryny może rozpocząć się od tej rodziny zamiast domyślnej. Odpowiedź wskazuje ją w profile, tak jak w przypadku każdej rodziny wybranej przez mechanizm rotacji.

Jawne wartości profile, browser, os lub version w wewnętrznym obiekcie request nigdy nie są nadpisywane, podobnie jak żądanie zawierające własny nagłówek User-Agent lub Cookie, ponieważ autoryzacja clearance jest powiązana z sygnaturą, która ją uzyskała.


Żądanie Browser

POST /api/browser/

Otwiera podany URL w instancji przeglądarki Chrome. Strona się ładuje, wykonywany jest kod JavaScript, a w rezultacie otrzymujesz w pełni wyrenderowany kod HTML wraz z plikami cookie.

Treść żądania

Parametr Typ Wymagany Domyślnie Opis
url string Tak - Docelowy URL
headers object Nie - Niestandardowe nagłówki jako pary klucz-wartość
cookies array Nie - Pliki cookie do ustawienia: [{name, value, domain?}]
userAgent string Nie - Niestandardowy ciąg User-Agent
unblocker boolean Nie true Wykonuje weryfikację wymaganą przez stronę przed jej załadowaniem (strona challenge lub podobna blokada). Domyślnie włączone. Ustaw false, aby renderować dokładnie to, co zwraca strona, w tym stronę challenge.
proxy string Nie - Identyfikator proxy z wcześniejszej odpowiedzi, aby przypiąć ten sam węzeł wyjściowy. Przekaż nieprzezroczysty ciąg znaków bez zmian. Bezpośredni adres proxy jest odrzucany z błędem 400 Invalid proxy format.
timeout_ms number Nie 30000 Limit czasu ładowania strony w ms (maks.: 120000)
checkStatus number Nie - Oczekiwany status HTTP (żądanie kończy się błędem, jeśli jest inny)
checkText string Nie - Tekst, który musi pojawić się na wyrenderowanej stronie
lean boolean Nie false Pomija obrazy, czcionki, multimedia oraz żądania do znanych usług reklamowych, analitycznych, zgód i społecznościowych. Sama strona, jej skrypty, style oraz elementy wymagane przez krok weryfikacji nadal się ładują. Użyj tego, aby zmniejszyć transfer zużywany przez stronę, na przykład przez przypięty węzeł premium.

Dopasowywanie zegara przeglądarki do węzła wyjściowego

Strona może odczytać strefę czasową przeglądarki i porównać ją z krajem adresu IP, który widzi. Rozbieżność to jeden z najprostszych sygnałów dla systemów wykrywania botów, a jej eliminacja nic nie kosztuje.

Nie musisz nic robić. FourA odczytuje kraj z identyfikatora proxy, a przeglądarka zgłasza odpowiednią dla niego strefę czasową.

  • Chodzi o kraj węzła wyjściowego, czyli kraj widziany przez cel, a nie miejsce hostowania proxy. Te dwie lokalizacje różnią się na tyle często, że ma to znaczenie.
  • Jeśli FourA nie zna kraju węzła wyjściowego, pozostawia zegar przeglądarki bez zmian, zamiast zgadywać. Węzeł premium ma znany kraj, jeśli został wskazany za pomocą exitCountries w Proxy Request.
  • Tylko zegar dostosowuje się do kraju. Nagłówek Accept-Language oraz treść serwowana przez witrynę pozostają nienaruszone, więc strona nie zmieni niespodziewanie języka.

Parametr userAgent

Wyślij userAgent, a strona, jej procesy worker i cel zobaczą dokładnie ten ciąg. FourA generuje z niego także dopasowane client hints (sec-ch-ua, sec-ch-ua-platform, navigator.platform oraz wartości o wysokiej entropii, których detektor wymaga bezpośrednio), dzięki czemu żądanie nie wskazuje na inną przeglądarkę w nagłówku, a inną w JavaScript.

Wartość userAgent w odpowiedzi to ta, która została faktycznie użyta. Ma to znaczenie przy ponownym użyciu clearance: plik cookie cf_clearance jest powiązany z węzłem wyjściowym oraz ciągiem User-Agent, który go uzyskał, dlatego należy odesłać ciąg zwrócony w odpowiedzi, a nie ten, którego użycie zakładano. Zobacz Site checks.

Wyślij ciąg inny niż Chromium (na przykład User-Agent przeglądarki Firefox), a zostanie on przesłany w niezmienionej formie, bez dołączonej listy marek Chromium.

Przykład

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"]}
}
Pole Typ Opis
status number Kod statusu HTTP z serwera docelowego
headers object Nagłówki odpowiedzi
body string lub object W pełni wyrenderowana zawartość strony. Ciąg znaków HTML, gdy content-type to HTML; obiekt, gdy strona zwróciła JSON i został on automatycznie sparsowany.
cookies array Pełne obiekty cookie ze strony. Każde cookie zawiera name, value, domain, path, expires, httpOnly, secure, sameSite oraz inne właściwości cookie.
userAgent string Użyty User-Agent przeglądarki
defenseSolved boolean true, jeśli podczas tego wywołania napotkano i rzeczywiście ominięto ochronę przed botami; w przeciwnym razie false. Decyduje o tym, czy wywołanie kosztuje 5 czy 10 kredytów.
defenses object present wymienia każdego dostawcę zabezpieczeń wykrytego podczas ładowania strony, cleared wymienia tych, których autoryzację zachowała ostateczna strona. Dostawca może pojawić się w present i nigdy w cleared. Zobacz Weryfikacje stron.
proxy string Zakodowany identyfikator proxy, przez który przeszło żądanie (tylko wtedy, gdy w żądaniu podano proxy). Użyj go ponownie w kolejnych wywołaniach, aby zachować ten sam węzeł wyjściowy.
error string Komunikat o błędzie, jeśli żądanie się nie powiodło

Przypinanie węzła wyjściowego

Wartość proxy w żądaniu Single lub Browser przypina węzeł wyjściowy użyty przez poprzednie wywołanie. Przekaż nieprzezroczysty identyfikator dokładnie w takiej postaci, w jakiej został zwrócony, nigdy jako adres proxy. Identyfikator z żądania Proxy, który określał kraj, lokalizację lub czas życia, zachowuje te parametry, więc przypięte żądanie nie wymaga żadnego innego pola.

Odrzucane są trzy wartości, wszystkie z kodem 400:

Błąd Znaczenie
Invalid proxy format Wartość nie jest identyfikatorem wystawionym przez FourA. Bezpośredni adres proxy skutkuje tym błędem.
Proxy not found Identyfikator został zdekodowany, ale nie wskazuje już na aktywny węzeł wyjściowy. Pobierz nowy identyfikator z nowego wywołania.
Managed exit: this proxy id cannot be pinned to a request Węzeł wyjściowy istnieje, ale nie jest węzłem, który FourA utrzyma dla wskazanego żądania. Identyfikator węzła premium trafi tutaj, gdy w Twoim planie skończy się transfer premium. Użyj ponownie sesji, w której został zwrócony, lub wykonaj wywołanie przez POST /api/proxy/ i zaakceptuj dowolny wybrany przez nie węzeł wyjściowy.

Przypięty węzeł wyjściowy premium jest rozliczany jako ruch premium. Odpowiedź zawiera X-FourA-Exit-Class: premium, dzięki czemu można monitorować go dla każdego żądania, a ruch obsłużony przez węzeł wlicza się do limitu transferu premium na stronie Użycie i limity, jak również do całkowitej przepustowości, niezależnie od tego, czy witryna zwróciła żądaną stronę. Przypinanie wymaga dostępności węzłów premium w Twoim planie oraz pozostałego limitu; w przeciwnym razie identyfikator zostanie odrzucony z powyższym błędem 400 dla zarządzanego węzła.

Kody statusu HTTP

Kod Znaczenie
200 Żądanie zakończone (sprawdź wewnętrzne status dla odpowiedzi docelowej)
400 Nieprawidłowa treść żądania, parametry, docelowy IP w zakresie prywatnym/zarezerwowanym, cel na własnym hoście API FourA, adres URL z niezakodowaną spacją (Single, Proxy, Auto) lub identyfikator proxy, którego nie można przypiąć. W Single, Proxy i Browser pole, które nie przeszło walidacji, jest nazwane: Invalid request: <field>: <reason>, maksymalnie do pięciu pól. Brak opłaty. Auto odpowiada na ten sam błąd kodem HTTP 200 i status: 400 w treści.
401 Brakujący lub nieprawidłowy klucz API
403 Endpoint lub parametr nie jest dostępny w Twoim planie. X-FourA-Limit wskazuje: plan_limit_feature lub plan_limit_premium.
404 Not Found: brak endpointu pod tą ścieżką.
413 Treść żądania JSON przekracza 100 KB. Odpowiedź nie jest formatem JSON i nie zawiera nagłówka X-FourA-Request-Id.
429 Limit planu (ustawiony nagłówek X-FourA-Limit) lub współdzielony limit platformy na minutę (brak nagłówka)
500 Wewnętrzny błąd serwera
502 Upstream unavailable: FourA nie mogło połączyć się ze swoim silnikiem. Malformed JSON from backend: silnik odpowiedział, ale FourA nie mogło odczytać odpowiedzi. Ponów próbę.
503 Usługa tymczasowo wyłączona lub przeciążona, API key check temporarily unavailable, gdy FourA nie mogło chwilowo potwierdzić Twojego klucza (ponów próbę po upływie Retry-After), lub Backend service unavailable podczas restartu silnika. W trybie Browser strona czeka do 10 sekund na wolną przeglądarkę, gdy wszystkie są zajęte, i otrzymuje Backend service unavailable, jeśli żadna nie zwolni się w tym czasie.
504 Upstream timeout. Silnik nie ukończył działania w wyznaczonym limicie czasu dla tego żądania. Zwiększ timeout_ms lub ponów próbę.

Kolejne kroki

Aktualizacja: 13 listopada 2026