# Port proxy

> URL: https://foura.ai/pl/docs/api/proxy-port
> Updated: 2026-10-15
> Index: https://foura.ai/llms.txt

Wysyłaj własny ruch przez węzły wyjściowe FourA z dowolnego klienta obsługującego proxy URL: przeglądarki, narzędzia do pobierania czy scrapera, którego już używasz. Port proxy otwiera tunel do wskazanego celu i kopiuje bajty w obu kierunkach, obsługując to, czego nie wspiera JSON API: strumienie danych, duże pliki i całe sesje przeglądarki.

## Connecting

| Setting | Value |
|---------|-------|
| Host | `proxy.foura.ai` |
| Port | `34004` |
| Protocol | HTTP CONNECT with Basic authentication |
| Target ports | `443` and `80` |

Dane uwierzytelniające znajdziesz w panelu. Utwórz użytkownika proxy w sekcji **Proxy** w menu bocznym, aby wygenerować login i hasło. Są one celowo odseparowane od klucza API: uzgadnianie połączenia proxy (handshake) jest przesyłane jawnym tekstem przy każdym połączeniu, a dane użytkownika proxy można rotować bez modyfikacji integracji API. Zobacz [Proxy Users](https://foura.ai/docs/dashboard/proxy).

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 https://example.com
```

```python
import requests

proxy = "http://USERNAME:PASSWORD@proxy.foura.ai:34004"
r = requests.get("https://example.com", proxies={"https": proxy, "http": proxy})
print(r.status_code)
```

Port obsługuje wyłącznie CONNECT. Cel `https://` jest tunelowany przez każdego klienta. Zwykły cel `http://` działa, gdy klient również go tuneluje (curl: `--proxytunnel`); klient, który zamiast tego przesyła zwykły request do proxy, otrzymuje `405 Method Not Allowed`.

## Opcje przekazywane w nazwie użytkownika

Wszystko po danych uwierzytelniających to lista par `-key-value`, w dowolnej kolejności:

```
USERNAME-network-premium-country-de-session-a1
```

Wartosci to slowa pisane malymi literami. Myslnik wewnatrz wartosci rozpoczyna nowa opcje, wiec `-city-new-york` jest interpretowane jako dwie opcje i odrzucane. Nieznany klucz rowniez jest odrzucany, a nie pomijany: blednie wpisany `-contry-de` zwraca blad 400 z lista obslugiwanych kluczy, zamiast obslugiwac ruch z niewlasciwego kraju.

| Opcja | Wartosci | Dzialanie |
|--------|--------|--------------|
| `network` | `shared` (domyslnie, alias `pool`), `premium` (alias `residential`) | Siec, z ktorej pochodzi adres. Shared to wlasne wezly wyjsciowe FourA, wliczone w plan. Premium to adresy domowe, pobierane z transferu premium dostepnego w planie i dokupionych pakietow. |
| `fallback` | `premium` (alias `residential`), `off` | Tylko siec shared. Przelacza na wezel premium, gdy siec shared nie moze zrealizowac zapytania. Domyslnie wylaczone; dziala tylko wtedy, gdy plan obejmuje transfer premium i pozostal dostepny limit. |
| `country` | ISO 3166-1 alpha-2, wielokrotnego uzytku | Kraj wyjsciowy widziany przez cel. Powtorz dla zakresu obejmujacego wiele krajow: `-country-de-country-fr`. |
| `session` | Od 1 do 32 liter, cyfr lub znakow podkreslenia | Polaczenia o tej samej nazwie wspoldziela adres (sticky). Pomin, aby uzyskac nowy adres dla kazdego polaczenia (rotating). |
| `state` | slowo | Region. Tylko premium. |
| `city` | slowo | Miasto. Tylko premium. |
| `asn` | liczba | Siec, wedlug numeru AS. Tylko premium. |
| `os` | `windows`, `android`, `ios`, `mac` | Typ urzadzenia, do ktorego nalezy adres. Tylko premium. |
| `lifetime` | `3` do `1440` | Czas utrzymania stalego adresu premium w minutach. Tylko premium. |

Kazda opcja z wyjatkiem `network`, `fallback` i `session` akceptuje `any`, co czysci wartosc zapisana dla uzytkownika proxy dla tego jednego polaczenia.

Trzy kombinacje sa odrzucane z kodem 400 zamiast czesciowego wykonania:

- `state`, `city`, `asn`, `os` lub `lifetime` w sieci shared. Siec shared wybiera sie wylacznie wedlug kraju; dodaj `-network-premium`, aby kierowac ruch na miasto.
- `-fallback-premium` razem z `-network-premium`. Fallback nie ma zastosowania w sieci, do ktorej nastepuje przelaczenie.
- Bardziej precyzyjne targetowanie przy aktywnym fallbacku. Fallback moze, ale nie musi sie uruchomic, wiec zadanie miasta, ktore mogloby byc spelnione tylko czasami, jest odrzucane.

### Sesje

W sieci shared nazwana sesja utrzymuje ten sam punkt wyjsciowy tak dlugo, jak z niego korzystasz, w ruchomym oknie dziesieciominutowym. Jesli ten punkt wyjsciowy przestanie dzialac, sesja zostanie przeniesiona na inny zamiast zakonczenia bledem. Przegladarka sterowana przez ten port powinna zawsze przekazywac nazwe sesji: ladowanie strony otwiera dziesiatki polaczen, a bez sesji kazde z nich wychodzi z innego adresu.

W sieci premium nazwana sesja utrzymuje swoj adres przez `lifetime` min, lub przez domyslny czas sieci, gdy go nie ustawisz.

### Zapisane ustawienia domyslne

Targetowanie zapisane dla użytkownika proxy w panelu ma zastosowanie do każdego nawiązanego przez niego połączenia, dzięki czemu nazwa użytkownika może pozostać krótka. Wszystko, co umieścisz w nazwie użytkownika, ma pierwszeństwo dla tego konkretnego połączenia, a `any` przywraca zapisaną wartość. Zapisana domyślna opcja premium zużywa środki tylko wtedy, gdy pozwala na to Twój plan; w przeciwnym razie połączenie jest obsługiwane z sieci współdzielonej, a tunel i tak zostaje otwarty.

### Nagłówki CONNECT

Klient, który może dodawać nagłówki do żądania CONNECT, może przesłać te same opcje jako nagłówki. Nagłówek ma pierwszeństwo przed tą samą opcją podaną w nazwie użytkownika.

| Nagłówek | Odpowiednik |
|--------|---------|
| `X-Foura-Network` | `-network-` |
| `X-Foura-Fallback` | `-fallback-` (`premium` lub `off`) |
| `X-Foura-Country` | `-country-`, rozdzielone przecinkami dla wielu |
| `X-Foura-Session` | `-session-` |
| `X-Foura-State` | `-state-` |
| `X-Foura-City` | `-city-` |
| `X-Foura-Asn` | `-asn-` |
| `X-Foura-Lifetime` | `-lifetime-` |

```bash
curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 \
  --proxy-header "X-Foura-Country: de" \
  https://example.com
```

## Odpowiedzi

Tunel, który się otwiera, zwraca `200 Connection established`. Każda odmowa po sprawdzeniu danych uwierzytelniających zawiera nagłówek `X-Foura-Error` z jednolinijkowym powodem, dlatego sprawdź ten nagłówek w pierwszej kolejności.

| Status | Kiedy |
|--------|-------|
| 400 Bad Request | Nieprawidłowo sformatowane żądanie lub opcja, której FourA nie może obsłużyć. `X-Foura-Error` wskazuje tę opcję oraz obsługiwane wartości. |
| 403 Forbidden | Port docelowy nie jest obsługiwany, cel nie jest publicznym hostem internetowym, port nie jest objęty Twoim planem lub podano `-network-premium`, a w Twoim planie skończył się transfer premium bądź plan nie obejmuje sieci premium. |
| 405 Method Not Allowed | Zwykłe żądanie zamiast CONNECT. |
| 407 Proxy Authentication Required | Brakujące lub błędne dane uwierzytelniające. Odpowiedź nigdy nie wskazuje, która część była niepoprawna. |
| 408 Request Timeout | Klient połączył się i nie przesłał żadnych danych przez 15 sekund. |
| 431 Request Header Fields Too Large | Nagłówki żądania CONNECT przekroczyły 16 KB. |
| 429 Too Many Requests | Przekroczenie jednego z limitów Twojego planu: jednocześnie otwartych tuneli, liczby otwieranych tuneli na minutę lub standardowego transferu w tym okresie rozliczeniowym. Występuje także wtedy, gdy sam port osiągnie maksymalną pojemność lub limit tempa otwierania. `X-Foura-Error` wskazuje konkretną przyczynę. |
| 502 Bad Gateway | Nie znaleziono działającego węzła wyjściowego dla danego celu w wyznaczonym limicie czasu wyboru lub własny mechanizm rozwiązywania nazw FourA nie mógł rozpoznać hosta. Są to dwa różne komunikaty w `X-Foura-Error`. |
| 503 Service Unavailable | Port proxy jest wyłączony. |

## Limity

- Liczba jednocześnie otwartych tuneli oraz liczba otwieranych tuneli na minutę wynikają z Twojego planu i są zliczane dla całego konta, a nie dla pojedynczego użytkownika proxy: wygenerowanie drugiego zestawu danych uwierzytelniających nie zwiększa limitu. Twoje limity znajdują się na stronie [Usage & Limits](https://foura.ai/docs/dashboard/quota).
- Wyszukiwanie węzła wyjściowego trwa do 45 sekund, zanim port zwróci błąd 502. Sesja, która ma już przypisany węzeł wyjściowy, zazwyczaj łączy się w czasie znacznie poniżej jednej sekundy.
- Tunel, w którym nie są przesyłane żadne bajty w żadnym kierunku, jest zamykany po dwóch minutach bezczynności.
- W przypadku aktualizacji portu otwarte już tunele otrzymują nieco poniżej trzech minut na zakończenie działania, po czym są zamykane, podczas gdy nowe połączenia są nieprzerwanie otwierane. Długie pobieranie lub strumieniowanie powinno wznowić połączenie po zamknięciu tunelu.
- Użytkownik proxy wyłączony lub usunięty w panelu przestaje być uwierzytelniany w ciągu minuty.

## Rozliczanie zużycia

Bajty przesłane przez port wliczają się do transferu na stronie [Usage & Limits](https://foura.ai/docs/dashboard/quota), a bajty przesłane przez węzeł wyjściowy premium wliczają się również do Twojego transferu premium: te same bajty są raportowane w dwóch miejscach, lecz nigdy nie są sumowane. Gdy tunel się otworzy, ruch wygenerowany przez próby użycia węzłów wyjściowych premium, których port ostatecznie nie wykorzystał, także wlicza się do transferu premium. Niewykorzystane próby w sieci współdzielonej nie są zliczane, a w przypadku gdy żaden tunel się nie otworzy, nie jest naliczany żaden transfer.

Standardowy transfer, z którego może korzystać port, wynika z Twojego planu. W planie opartym na kredytach port ma własne dołączone gigabajty, a dodatkowe można dokupić na stronie Billing; w planie rozliczanym według transferu korzysta on z tej samej puli co API. Po jej wyczerpaniu nowe połączenia są odrzucane do momentu zresetowania okresu lub dokupienia limitu, a wiadomości e-mail o zużyciu informują o terminach.

Po wyczerpaniu limitu premium trzy sposoby dostępu do tej sieci są celowo obsługiwane inaczej. Połączenie wskazujące `-network-premium` jest odrzucane z kodem 403 z odpowiednią informacją, ponieważ klient proszący o płatne zasoby i po cichu obsłużony z innego miejsca ponawiałby zapytania i oczekiwał pozycji premium, która się nie pojawi. Fallback nie jest uruchamiany, a domyślne ustawienie premium zapisane dla użytkownika proxy zostaje zdegradowane do sieci współdzielonej, co nadal otwiera tunel: żaden z tych przypadków nie zakładał naliczania opłat za to konkretne połączenie.

## Powiązane

- [Proxy Users](https://foura.ai/docs/dashboard/proxy): Tworzenie użytkowników proxy i generowanie connection string w panelu
- [Proxy Request](https://foura.ai/docs/api/endpoints#proxy-request): Alternatywne JSON API z wbudowanymi ponowieniami i walidacją
- [Reuse a Proxy Across Requests](https://foura.ai/docs/how-to/reuse-a-proxy): Utrzymywanie jednego węzła wyjściowego w JSON API
- [Usage & Limits](https://foura.ai/docs/dashboard/quota): Przepustowość i transfer premium w ramach Twojego planu