Dokumentacja › Referencja API › Dokumentacja punktów końcowych API

Dokumentacja punktów końcowych API

Dokumentacja wszystkich endpointów API FourA wraz z parametrami żądań i formatami odpowiedzi.

Bazowy adres URL

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

Uwierzytelnianie

Każde żądanie wymaga klucza API w nagłówku 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

Każda odpowiedź z /api/* zawiera dwa nagłówki korelacyjne:

Nagłówek Wartość Opis
X-FourA-Request-Id UUID Unikalny identyfikator przypisany do requestu. Zwracany w każdej odpowiedzi, w tym 4xx i 5xx. Zapisz go w swoich logach.
X-FourA-Credits integer Kredyty zużyte na ten request. Zwracane przy sukcesie i błędzie (praca została wykonana w obu przypadkach). Zobacz Wyniki requestów, aby dowiedzieć się, które wyniki podlegają opłacie.

Ten sam request ID jest kluczem dla podglądu payloadu requestu i odpowiedzi w Activity Log Dashboardu (przechowywane przez 24 godziny, ostatnie 200 na klucz), dzięki czemu możesz później odszukać dokładny request i odtworzyć go z sekcji Activity bezpośrednio w Playground. Podaj go, gdy kontaktujesz się z pomocą techniczną, a pozwoli to zidentyfikować request 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 Nagłówki odpowiedzi, aby uzyskać pełną listę i wskazówki dotyczące użycia.

Endpoints

Używasz tych endpoints przez MCP? Serwer @fouradata/mcp opakowuje wszystkie cztery endpoints jako natywne narzędzia MCP (foura_auto, foura_single, foura_proxy, foura_browser) z takimi samymi strukturami wejściowymi oraz dodatkową opcją offload_large dla przyjaznej tokenom obsługi dużych odpowiedzi.

FourA udostępnia cztery request endpoints, z których każdy jest zoptymalizowany pod kątem innego scenariusza:

Endpoint Najlepsze dla
POST /auto/ Smart fetch. Przekazujesz URL, FourA wybiera najtańszą działającą ścieżkę (bezpośrednią, rotowane proxy lub przeglądarkę) i zapamiętuje, co działa dla danego hosta.
POST /single/ Szybkie żądania HTTP, strony statyczne, API
POST /proxy/ Chronione strony z automatyczną rotacją proxy, opcjonalne określanie 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.

Aby uzyskać szczegółowe omówienie, kiedy wybrać który z nich, zobacz Wybór właściwego endpointu oraz przewodnik po Smart Fetch.

Ograniczenia docelowego URL

Cele, które rozwiązują się na prywatne, zwrotne lub zarezerwowane pule IP (RFC 5735, RFC 6598, zarezerwowane bloki IPv6), są odrzucane statusem 400 zanim request opuści FourA. Przekazywane są tylko publiczne nazwy hostów i adresy IP.

{ "error": "Target <ip> resolves to a private/reserved IP" }

Smart Fetch (Auto)

POST /api/auto/

Przekazujesz URL oraz opcjonalne reguły validate. FourA przechodzi przez optymalizującą koszty ścieżkę (tanie bezpośrednie zapytanie, rotacyjne proxy, pełna przeglądarka) i zatrzymuje się na pierwszym kroku, który zwróci odpowiedź akceptowaną przez twoje reguły. Przy kolejnych żądaniach do tego samego hosta odtwarzana jest aktywna sesja, dzięki czemu drugie zapytanie jest tanie.

Nie musisz konfigurować ponowień, rozmiarów puli ani liczby proxy. FourA uczy się ich dla każdego hosta.

Ciało żądania

Parametr Typ Wymagane Domyślnie Opis
url string Tak - Docelowy URL
method string Nie "GET" Metoda HTTP
headers [string, string][] Nie - Niestandardowe nagłówki jako pary [nazwa, wartość]
data any Nie - Ciało żądania dla zapytań innych niż GET
validate object Nie - Kryteria sukcesu, w tym samym formacie co validate w Single Request (patrz poniżej). Określ jak wygląda prawdziwa strona, aby automat mógł odróżnić właściwą treść od strony z wyzwaniem.
returnSession boolean Nie true Dołącz zwycięską sesję (proxy, cookies, userAgent) w odpowiedzi, aby móc ją odtworzyć przez /api/single/ lub /api/browser/.
forceProxy boolean Nie true Zawsze kieruj ruch przez rotacyjne proxy. Ustaw na false, aby zezwolić na tańszą ścieżkę bezpośrednią, jeśli cel na to pozwala (niektóre zabezpieczenia są bardziej restrykcyjne dla ruchu z proxy).
timeout_ms integer Nie 120000 Całkowity budżet czasowy dla całego wywołania w milisekundach. Wszystkie próby są realizowane w ramach tego budżetu. Min 5000, max 180000.
ignoreProxies string[] Nie - Identyfikatory proxy do pominięcia w każdej próbie. Użyj identyfikatorów zwróconych w poprzednich odpowiedziach /api/auto/ lub /api/proxy/.
followRedirects integer Nie 5 Maksymalna liczba przekierowań na tanich szczeblach ścieżki. 0, aby wyłączyć. Maksimum 20.

Odpowiedź

{
  "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..."
  }
}
Pole Typ Opis
status number Status HTTP z celu.
data string lub object Ciało odpowiedzi.
headers array lub object Nagłówki odpowiedzi celu. Wywołania single i proxy zwracają tablicę obiektów nagłówków dla każdego skoku, wywołania browser zwracają płaski obiekt.
meta.rung string Który etap drabinki dostarczył odpowiedź. Jeden z: probe (tani bezpośredni request), proxy (rotacyjne proxy), browser (pełne renderowanie w przeglądarce), cache (odtworzenie rozgrzanej sesji) lub fail (żaden etap nie wygenerował akceptowanej odpowiedzi).
meta.solved boolean Czy wyzwanie bota zostało rozwiązane podczas tego wywołania.
meta.attempts number Liczba prób pobocznych wykonanych przed sukcesem.
meta.credits number Całkowita liczba kredytów wydana na to wywołanie. Odpowiada X-FourA-Credits.
session.proxy string Zakodowane ID proxy, które dostarczyło odpowiedź. Można użyć go ponownie w requeście Single lub Browser. Obecne, gdy returnSession ma wartość true.
session.cookies array Ciasteczka (cookies) ze zwycięskiej próby. Obecne, gdy returnSession ma wartość true.
session.userAgent string User-Agent użyty w zwycięskiej próbie. Obecny, gdy returnSession ma wartość true.
error string Komunikat o błędzie, jeśli wywołanie się nie powiodło.

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 to koordynator. Wywołuje wewnętrznie Single, Proxy lub Browser i przekazuje klucz API do każdego podwywołania. Każde podwywołanie pojawia się w Twoim Dzienniku aktywności; zewnętrzne wywołanie /api/auto/ nie dodaje osobnego płatnego wiersza.
  • Przekaż validate.data.accept z podciągiem, który zawiera tylko prawdziwa strona. Bez tego auto nie odróżni prawdziwego statusu 200 od strony weryfikacyjnej zwróconej ze statusem 200.
  • timeout_ms ogranicza czas całego wywołania. Pierwsze wejście na chronioną stronę może zająć kilkadziesiąt sekund; ponownie użyte ciepłe sesje zazwyczaj kończą się w mniej niż sekundę.

Single Request

POST /api/single/

Wysyła request HTTP z realistyczną charakterystyką sieciową podobną do przeglądarki, bez uruchamiania prawdziwej przeglądarki. Jest to najszybszy endpoint.

Request Body

Paramетr 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} gdziekolwiek w adresie URL, aby wstawić aktualny znacznik czasu dla ominięcia pamięci podręcznej.
headers [string, string][] Nie - Niestandardowe nagłówki jako pary [nazwa, wartość]
unblocker boolean Nie true Wyślij realistyczne nagłówki przeglądarki (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Włączone domyślnie. Ustaw na false, aby wysłać zwykłą sygnaturę klienta.
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 akceptację 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 Pamięć podręczna DNS TTL w sekundach (maks.: 240)
followRedirects number Nie wyłączone Maksymalna liczba przekierowań do śledzenia (0-20). Pomiń, aby wyłączyć.
tryJsonData boolean Nie false Analizuj ciało odpowiedzi jako JSON, jeśli to możliwe
returnBuffer boolean Nie false Zwróć surowy bufor zamiast zdekodowanego ciągu znaków
data any Nie - Ciało zapytania (ciąg znaków lub obiekt, automatycznie serializowane do JSON)
proxy string Nie - Identyfikator proxy z wcześniejszej odpowiedzi, aby przypiąć to samo wyjście. Przekaż nieprzezroczysty ciąg znaków w niezmienionej formie. Surowy adres proxy jest odrzucany z błędem 400 Invalid proxy format.
browser string Nie Chrome Przeglądarka do prezentacji: Chrome, Edge, Safari, Firefox lub Tor. Zobacz Profile przeglądarki.
os string Nie - System operacyjny do prezentacji: Windows, macOS, Android lub iOS. Nazwa rodziny akceptuje każdą z jej wersji.
version string Nie newest Wersja przeglądarki do prezentacji, zgodnie z wykazem w katalogu. Zwycięża najnowsze dopasowanie, gdy kilka pasuje.
profile string Nie - Dokładny identyfikator profilu z GET /api/profiles, zamiast trzech powyższych pól.
validate object Nie - Reguły sprawdzania poprawności odpowiedzi (zobacz poniżej)

Profile przeglądarki

Domyślnie żądanie prezentuje najnowszą wersję Google Chrome. Niektóre cele akceptują jedną przeglądarkę, a odrzucają inną, więc browser, os i version zawężają katalog zmierzonych profili, a profile wybiera jeden 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 unblockerze nie są wysyłane żadne nagłówki przeglądarki, więc request jest odrzucany, a nie częściowo stosowany.
  • Gdy pasuje kilka profili, wygrywa najnowsza wersja.
  • Kombinacja, której katalog nie może przedstawić, zwraca błąd ze wskazaniem dostępnych opcji. 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ść do filtrowania podczas tworzenia selektora; os przechowuje nazwę wydania do wyświetlenia.

Reguły walidacji

Obiekt validate pozwala zdefiniować warunki powodzenia i niepowodzenia. Jeśli warunek fail zostanie spełniony, request jest traktowany jako nieudany. Jeśli ustawiono warunki accept, tylko pasujące response 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 Pary klucz-wartość w nagłówku, które muszą być obecne
validate.headers.fail object Pary klucz-wartość w nagłówku, które powodują błąd
validate.data.accept string[] Ciągi znaków, które muszą pojawić się w ciele odpowiedzi
validate.data.fail string[] Ciągi znaków w ciele odpowiedzi, które powodują błąd

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

Odpowiedź:

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342,
  "proxy": "A1B2C3"
}

Gdy cel przeprowadza weryfikację pod kątem botów przed zwróceniem body, odpowiedź zawiera również obiekt defense wskazujący dostawcę oraz informację, czy weryfikacja przebiegła pomyślnie:

{
  "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żde przekierowanie. Każdy zawiera pole result z linią statusu oraz wszystkimi nagłówkami odpowiedzi. Nagłówki o wielu wartościach (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óre przeszło żądanie (tylko gdy w żądaniu podano proxy). Użyj go ponownie w kolejnym wywołaniu, aby przypiąć to samo wyjście.
defense object Obecne tylko wtedy, gdy serwer docelowy przeprowadził weryfikację pod kątem botów dla tego żądania. defense.solved określa, czy weryfikacja zakończyła się sukcesem. Zobacz Zabezpieczenia przed botami dla każdego pola i pełnej listy dostawców.
error string Komunikat o błędzie, jeśli żądanie się nie powiodło

Żądanie przez proxy

POST /api/proxy/

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

Ciało żądania

Parametr Typ Wymagane Domyślnie Opis
request object Tak - Ciało pojedynczego żądania (te same pola co w Single Request powyżej)
timeout_ms number Nie 45000 Całkowity limit czasu dla wszystkich prób w ms (maks: 120000)
maxTries number Nie 5 Maksymalna liczba prób rotacji proxy (maks: 90)
ignoreProxies string[] Nie - Identyfikatory proxy wykluczone 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, zmieniane na wielkie litery i pozbawiane duplikatów. Proxy o nieznanych wyjściach są wykluczone, a żądanie nigdy nie wraca do nieżądanego kraju.

Ograniczanie za pomocą exitCountries

Wybór korzysta z najnowszych dostępnych metadanych krajów widocznych dla celu, zazwyczaj odświeżanych w ciągu około dziesięciu minut. Nie jest to wyszukiwanie geolokalizacyjne w czasie rzeczywistym podczas wykonywania żądania. Nie wnioskuj o kraju serwującym na podstawie adresu hosta proxy.

Jeśli w obecnej puli nie ma krajów pasujących do żądanych, odpowiedź zwraca HTTP 200 wraz z obiektem 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 spróbuj ponownie później. Zmień go lub rozszerz tylko wtedy, gdy wymagania dotyczące kraju dla twojego przepływu pracy ulegną wyraźnej zmianie.

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, lub pomiń go w następnym żądaniu Proxy za pomocą ignoreProxies.
exitCountry string Dwuliterowy kod kraju proxy (widoczny dla celu), które obsłużyło żądanie. Obecny tylko wtedy, gdy żądanie ustawiło exitCountries. Przed zaufaniem odpowiedzi zawsze sprawdzaj, czy jest to jeden z kodów, o które prosiłeś.
total number Całkowity czas trwania mierzony zegarem ściennym w sekundach (float). Obejmuje wybór proxy, ponowienia i udaną próbę. total_time to tylko żądanie wewnętrzne; total zawsze jest >= total_time.
error string Komunikat o błędzie, jeśli żądanie się nie powiodło. W przypadku braku dopasowania zakresu code to no_eligible_proxy, a details.exitCountries odzwierciedla znormalizowany zakres.

Wszystkie pola odpowiedzi Single Request są również dołączone, w tym defense: próba użycia proxy, która napotkała sprawdzenie bota, zgłasza to w ten sam sposób co Single.

Żądanie Browser

POST /api/browser/

Otwiera URL w instancji przeglądarki Chrome. Strona się ładuje, JavaScript się wykonuje, a Ty otrzymujesz w pełni wyrenderowany HTML oraz zestaw plików cookie.

Ciało żądania (Request Body)

Parametr Typ Wymagany Domyślnie Opis
url string Tak - Docelowy URL
headers object Nie - Niestandardowe nagłówki jako pary klucz-wartość
cookies array Nie - Ciasteczka do ustawienia: [{name, value, domain?}]
userAgent string Nie - Niestandardowy ciąg User-Agent
unblocker boolean Nie true Automatyczne rozwiązywanie powszechnych wyzwań botów (odblokowanie Cloudflare, podobne bramki) podczas ładowania strony. Włączone domyślnie. Ustaw false, aby wyrenderować wszystko, co zwróci strona, w tym stronę z wyzwaniem, bez rozwiązywania.
proxy string Nie - Identyfikator proxy z wcześniejszej odpowiedzi, aby przypiąć to samo wyjście. Przekaż nieprzezroczysty ciąg znaków w postaci dosłownej. Surowy adres proxy zostaje odrzucony 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ę niepowodzeniem, jeśli jest inny)
checkText string Nie - Tekst, który musi pojawić się na wyrenderowanej stronie

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

Odpowiedź:

{
  "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"
}
Pole Typ Opis
status number Kod statusu HTTP celu
headers object Nagłówki odpowiedzi
body string or object W pełni wyrenderowana zawartość strony. String HTML, gdy content-type to HTML; object, gdy strona zwróciła JSON i została automatycznie sparsowana.
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 ochrona przed botami została napotkana i pomyślnie rozwiązana podczas tego wywołania. W przeciwnym razie brak. Decyduje o koszcie 15 lub 30 kredytów.
defenses object present listuje każdego dostawcę rozpoznanego podczas ładowania strony, cleared listuje tych, których rozwiązanie znajduje się na docelowej stronie. Dostawca może pojawić się w present i nigdy nie pojawić się w cleared. Zobacz Anti-Bot Defenses.
proxy string Zakodowane ID proxy, przez które przeszło żądanie (tylko wtedy, gdy dostarczono proxy w żądaniu). Użyj go ponownie w kolejnych wywołaniach, aby zachować to samo wyjście.
error string Komunikat błędu, jeśli żądanie się nie powiodło

Kody Statusu HTTP

Kod Znaczenie
200 Żądanie zakończone (sprawdź wewnętrzny status dla odpowiedzi celu)
400 Nieprawidłowe ciało żądania, parametry lub docelowe IP w prywatnym/zarezerwowanym zakresie
401 Brakujący lub nieprawidłowy klucz API
429 Przekroczono rate limit
500 Wewnętrzny błąd serwera
502 Upstream unavailable. FourA dotarło do silnika, ale odpowiedź była bezużyteczna. Ponów.
503 Usługa tymczasowo wyłączona lub przeciążona, albo Backend service unavailable podczas restartu silnika
504 Upstream timeout. Silnik nie zakończył pracy w zaplanowanym czasie dla tego żądania. Zwiększ timeout_ms lub ponów.

Następne kroki

Aktualizacja: 12 sierpnia 2026
Błędy API →