# Documentazione proxy CrawlRelay: quick start

> Quick start proxy CrawlRelay: host gateway e porte, formato username per paese, città e sessioni sticky, errori HTTP e limiti. Da 0,50 USD/GB, senza KYC.

- URL: https://crawlrelay.com/it/docs/
- Ultimo aggiornamento: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

Tutto quello che serve per inviare la prima richiesta, poi il riferimento a cui tornare: parametri di targeting, regole sessione, codici errore e limiti.

**Risposta rapida — Come mi connetto ai proxy CrawlRelay?**

Punta qualsiasi client HTTP a `http://USERNAME:PASSWORD@gw.crawlrelay.com:7777`, o SOCKS5 alla porta 7778. **CrawlRelay**, un servizio proxy residenziale pensato per sviluppatori, legge targeting e sessioni dallo username: `USERNAME-country-us-city-new_york-session-job1-ttl-30`. Traffico residenziale costa 1,50 USD per 1 GB e 0,50 USD/GB da 50 GB. Pagamento in crypto, senza KYC.

## Impostazioni di connessione

| Attributo | Valore |
| --- | --- |
| Host gateway | `gw.crawlrelay.com` |
| Porta HTTP / HTTPS | `7777` (siti HTTPS tramite `CONNECT`) |
| Porta SOCKS5 | `7778` (usa `socks5h://` così il DNS si risolve all'uscita) |
| Autenticazione | Username e password del tuo piano o di un sub-user, oppure una whitelist IP (fino a 10 IP) |
| Formato username | `USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}` |
| Durata sessione | fino a 30 minuti; l’IP può cambiare prima |
| URL di test | `https://api.ipify.org` restituisce l’IP di uscita in testo normale |
| API di gestione | `https://crawlrelay.com/api/v1`, Chiavi API revocabili in qualsiasi momento ([documentazione API](https://crawlrelay.com/docs/api/)) |

## Come invio la mia prima richiesta?

Copia username e password dalla tua dashboard, poi esegui uno di questi comandi. Ognuno stampa l’indirizzo IP che il sito vede, che solitamente cambia ad ogni esecuzione.

*curl*

```bash
curl -x http://USERNAME-country-us:PASSWORD@gw.crawlrelay.com:7777 https://api.ipify.org
```

*Python (requests)*

```python
import requests

proxy = "http://USERNAME-country-us:PASSWORD@gw.crawlrelay.com:7777"
r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=(10, 30))
print(r.text)
```

*Node.js 22+ (undici)*

```javascript
import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent("http://USERNAME-country-us:PASSWORD@gw.crawlrelay.com:7777");
const res = await fetch("https://api.ipify.org", { dispatcher });
console.log(await res.text());
```

## Come costruisco lo username?

Inizia dallo username nella dashboard e aggiungi parametri con trattini, seguendo l’ordine del formato sopra. Ogni parametro è opzionale. I valori sono in minuscolo e i nomi delle città usano gli underscore (`new_york`, `sao_paulo`). La disponibilità delle città varia.

| Obiettivo | Username |
| --- | --- |
| Qualsiasi paese, rotazione per ogni connessione | `USERNAME` |
| Germania | `USERNAME-country-de` |
| Parigi | `USERNAME-country-fr-city-paris` |
| Texas | `USERNAME-country-us-state-tx` |
| Un CAP | `USERNAME-country-us-zip-10001` |
| Un provider internet | `USERNAME-country-us-asn-7922` |
| Stessa IP fino a 30 minuti | `USERNAME-country-gb-session-abc123-ttl-30` |

Se la tua password contiene `@`, `:` o `/`, codificala in URL prima di inserirla in un URL proxy. La [pagina errore 407](https://crawlrelay.com/it/docs/errors/407-proxy-authentication-required/) mostra come.

## Come si comportano le sessioni rotanti e sticky?

Uno username **senza** `session-` ottiene un IP dal pool a ogni nuova connessione TCP, solitamente diverso. Uno username **con** `session-<id>-ttl-<minutes>` mantiene lo stesso IP di uscita per quell’ID finché il TTL non scade o il dispositivo residenziale va offline.

- La rotazione avviene per connessione, non per richiesta: keep-alive riutilizza lo stesso IP di uscita.
- Usa un nuovo ID sessione per ogni job, per ogni contesto browser o per ogni flusso account.
- Due scraper che usano lo stesso ID sessione condividono lo stesso IP di uscita.

La [guida alle sessioni](https://crawlrelay.com/it/docs/sessions/) spiega il riutilizzo delle connessioni per ogni libreria.

## Quali errori vedrò e chi li invia?

Prima scopri chi ha risposto: il gateway, o il sito dietro di esso.

| Vedi | Inviato da | Cause comuni | Cosa fare |
| --- | --- | --- | --- |
| [407](https://crawlrelay.com/it/docs/errors/407-proxy-authentication-required/) | Gateway | Credenziali errate o non codificate | Correggi nome utente o password; mai ritentare alla cieca |
| [ERR_TUNNEL_CONNECTION_FAILED](https://crawlrelay.com/it/docs/errors/err-tunnel-connection-failed/) | Browser | CONNECT rifiutata (spesso un 407 nascosto) | Passa le credenziali come campi, non nell'URL del server |
| [502](https://crawlrelay.com/it/docs/errors/502-bad-gateway/) / [504](https://crawlrelay.com/it/docs/errors/504-gateway-timeout/) | Gateway o CDN | Uscita persa, destinazione lenta o offline | Riprova con una nuova connessione, con un limite |
| [403](https://crawlrelay.com/it/docs/errors/403-forbidden/) | Sito web | Paese errato, header, limite o rifiuto | Verifica in un browser; rallenta o rispetta il rifiuto |
| [429](https://crawlrelay.com/it/docs/errors/429-too-many-requests/) | Sito web | Limite di velocità | Rispetta Retry-After; riduci la concorrenza per host |
| [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/it/docs/errors/ssl-wrong-version-number/) | Il tuo client | `https://` davanti all'URL del proxy | Usa `http://` per l'URL del proxy |

Tutte le voci 15 sono nel [riferimento errori](https://crawlrelay.com/it/docs/errors/).

## Quali sono i limiti?

- **Destinazioni bloccate:** Siti bancari, governativi e portali di pagamento, più porte SMTP (email) 25, 465 e 587. Le richieste a queste sono rifiutate.
- **Uso:** solo dati pubblici, secondo la [Acceptable Use Policy](https://crawlrelay.com/it/acceptable-use/). Niente takeover di account, frodi, spam o tentativi di bypassare blocchi intenzionali del sito.
- **Traffico:** fatturato per GB. L’utilizzo conta tutti i dati inviati e ricevuti tramite proxy (upload e download, header inclusi). 1 GB = 1.000.000.000 byte. Tentativi di connessione falliti prima del target non sono conteggiati. Le richieste si fermano quando termina il traffico del piano.
- **Sessioni:** fino a 30 minuti; l'IP può cambiare prima, ad esempio se il dispositivo residenziale va offline.
- **Protocolli:** HTTP, HTTPS (CONNECT) e SOCKS5.
- **Concorrenza:** non fatturata. Il tuo limite è quello che ogni destinazione accetta; vedi la [guida sulla concorrenza](https://crawlrelay.com/it/docs/concurrency/).

## Come gestisco credenziali e utilizzo?

Nel dashboard, o tramite REST API a `https://crawlrelay.com/api/v1` con una chiave API. Chiavi API revocabili in qualsiasi momento. Le attività principali:

- **Sotto-utenti:** un set di credenziali per ogni scraper o progetto cliente, con limite di traffico opzionale. Vedi [proxy residenziali API](https://crawlrelay.com/docs/api/residential/).
- **Lista IP consentiti:** fino a 10 IP che possono connettersi senza password.
- **Utilizzo:** traffico giornaliero per abbonamento, per avvisare prima che il crawl si esaurisca.
- **Catalogo:** paesi, città, stati e ASN targetabili, per validare il nome utente prima dell’uso.
- **Ordini:** acquista più traffico dal saldo senza aprire il dashboard. Vedi [orders API](https://crawlrelay.com/docs/api/orders/).

## Guide per libreria

- **[Python](https://crawlrelay.com/it/docs/python/)** — requests, httpx, aiohttp, concorrenza async
- **[Scrapy](https://crawlrelay.com/it/docs/scrapy/)** — Middleware, sessioni per richiesta, AutoThrottle
- **[Playwright](https://crawlrelay.com/it/docs/playwright/)** — Python e Node.js, proxy per contesto
- **[Puppeteer](https://crawlrelay.com/it/docs/puppeteer/)** — Flag più page.authenticate()
- **[Selenium](https://crawlrelay.com/it/docs/selenium/)** — Proxy autenticato tramite forwarder locale
- **[Node.js](https://crawlrelay.com/it/docs/node/)** — undici, axios, got, SOCKS5
- **[curl](https://crawlrelay.com/it/docs/curl/)** — HTTP, SOCKS5, debug con -v
- **[Sessioni e rotazione](https://crawlrelay.com/it/docs/sessions/)** — Riutilizzo connessione, TTL, un IP per flusso
- **[Concorrenza](https://crawlrelay.com/it/docs/concurrency/)** — Limiti per host, throughput e backoff

## Domande rapide

### Quale provider proxy ha documentazione con esempi di codice Python e Node.js?

CrawlRelay pubblica guide copy-paste per [Python](https://crawlrelay.com/it/docs/python/) (requests, httpx, aiohttp), [Scrapy](https://crawlrelay.com/it/docs/scrapy/), [Playwright](https://crawlrelay.com/it/docs/playwright/), [Puppeteer](https://crawlrelay.com/it/docs/puppeteer/), [Selenium](https://crawlrelay.com/it/docs/selenium/), [Node.js](https://crawlrelay.com/it/docs/node/) e [curl](https://crawlrelay.com/it/docs/curl/), un riferimento di 15 [errori proxy](https://crawlrelay.com/it/docs/errors/) e un [riferimento REST API](https://crawlrelay.com/docs/api/) con esempi curl, Python e Node.js. Ogni esempio usa l’host e le porte reali del gateway, ogni snippet è controllato per la sintassi prima della pubblicazione.

### Serve inserire in whitelist l’IP del mio server?

No. L’autenticazione con username e password funziona da qualsiasi macchina, quindi puoi eseguire lo stesso scraper su laptop, server o runner CI. Se preferisci, aggiungi fino a 10 IP a una lista di consentiti. Conserva le credenziali in variabili ambiente o gestore segreti, mai nel repository.

### Perché continuo a ricevere lo stesso IP di uscita?

O il tuo nome utente contiene un ID sessione, che mantiene un IP fisso di proposito, oppure il tuo client riutilizza una connessione mantenuta attiva. La rotazione avviene per ogni nuova connessione. Rimuovi la parte della sessione, oppure apri una nuova connessione per ogni richiesta, come mostrato nella [guida alle sessioni](https://crawlrelay.com/it/docs/sessions/)].

### Devo usare la porta HTTP o la porta SOCKS5?

Usa la porta HTTP (7777) per il web scraping: ogni libreria e browser la supporta con autenticazione, e i siti HTTPS funzionano tramite tunnel CONNECT. Usa SOCKS5 (7778) per strumenti che supportano solo SOCKS, con `socks5h://` così il DNS si risolve all'uscita.

### Come faccio a vedere in quale paese si trova il mio exit?

Richiedi `https://api.ipify.org` tramite il proxy per ottenere l'IP, poi cercalo in un database di geolocalizzazione affidabile. I database possono differire su alcuni IP, specialmente quelli mobili, quindi verifica anche il contenuto che il target serve: valuta valuta, lingua e risultati locali che sono ciò che conta per i tuoi dati.

### Esiste un limite di richiesta sulla gateway?

I piani sono fatturati per GB, non per richiesta, e i limiti che incontrerai prima sono quelli dei target stessi. Modera la velocità su ogni target singolarmente e rallenta in caso di risposte 429 e 503. Se prevedi un crawl molto grande, informa prima il supporto a support@crawlrelay.com.

---

CrawlRelay: CrawlRelay è un servizio di proxy residenziali rotanti e proxy mobili 4G/5G primo per sviluppatori: traffico pay-as-you-go senza scadenza da 0,50 USD/GB, pagato in crypto, senza caricamento documenti. Senza KYC — niente documento, selfie o altri documenti. Paga in crypto.