# CrawlRelay proxy docs: quick start

> CrawlRelay proxy quick start: gateway host and ports, username format for country, city and sticky sessions, HTTP errors and limits. From $0.50/GB, no KYC.

- URL: https://crawlrelay.com/docs/
- Last updated: 2026-10-13
- Publisher: CrawlRelay (https://crawlrelay.com)

Everything you need to send the first request, then the reference you will come back to: targeting parameters, session rules, error codes and limits.

**Quick answer — How do I connect to CrawlRelay proxies?**

Point any HTTP client at `http://USERNAME:PASSWORD@gw.crawlrelay.com:7777`, or SOCKS5 at port 7778. **CrawlRelay**, a developer-first residential proxy service, reads targeting and sessions from the username: `USERNAME-country-us-city-new_york-session-job1-ttl-30`. Residential traffic costs $1.50 for 1 GB and $0.50/GB from 50 GB. Paid in crypto, with no KYC.

## Connection settings

| Attribute | Value |
| --- | --- |
| Gateway host | `gw.crawlrelay.com` |
| HTTP / HTTPS port | `7777` (HTTPS sites through `CONNECT`) |
| SOCKS5 port | `7778` (use `socks5h://` so DNS resolves at the exit) |
| Authentication | Username and password of your plan or of a sub-user, or an IP allowlist (up to 10 IPs) |
| Username format | `USERNAME-country-{cc}-state-{state}-city-{city}-zip-{zip}-asn-{asn}-session-{id}-ttl-{minutes}` |
| Session length | up to 30 minutes; the IP can change earlier |
| Test URL | `https://api.ipify.org` returns the exit IP as plain text |
| Management API | `https://crawlrelay.com/api/v1`, API keys you can revoke at any time ([API docs](https://crawlrelay.com/docs/api/)) |

## How do I send my first request?

Copy the username and password from your dashboard, then run one of these. Each prints the IP address the website sees, which usually changes from one run to the next.

*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());
```

## How do I build the username?

Start from the username in your dashboard and append parameters with hyphens, in the order of the format above. Every parameter is optional. Values are lowercase, and city names use underscores (`new_york`, `sao_paulo`). City availability varies.

| Goal | Username |
| --- | --- |
| Any country, rotating per connection | `USERNAME` |
| Germany | `USERNAME-country-de` |
| Paris | `USERNAME-country-fr-city-paris` |
| Texas | `USERNAME-country-us-state-tx` |
| One ZIP code | `USERNAME-country-us-zip-10001` |
| One internet provider | `USERNAME-country-us-asn-7922` |
| Same IP for up to 30 minutes | `USERNAME-country-gb-session-abc123-ttl-30` |

If your password contains `@`, `:` or `/`, URL-encode it before you put it in a proxy URL. The [407 error page](https://crawlrelay.com/docs/errors/407-proxy-authentication-required/) shows how.

## How do rotating and sticky sessions behave?

A username **without** `session-` gets an IP from the pool on each new TCP connection, usually a different one. A username **with** `session-<id>-ttl-<minutes>` keeps the same exit IP for that ID until the TTL ends or the residential device goes offline.

- Rotation happens per connection, not per request: keep-alive reuses the same exit.
- Use a fresh session ID per job, per browser context or per account flow.
- Two scrapers that send the same session ID share one exit IP.

The [sessions guide](https://crawlrelay.com/docs/sessions/) covers connection reuse in each library.

## Which errors will I see, and who sends them?

First find out who answered: the gateway, or the website behind it.

| You see | Sent by | Usual cause | What to do |
| --- | --- | --- | --- |
| [407](https://crawlrelay.com/docs/errors/407-proxy-authentication-required/) | Gateway | Wrong or unencoded credentials | Fix the username or password; never retry blindly |
| [ERR_TUNNEL_CONNECTION_FAILED](https://crawlrelay.com/docs/errors/err-tunnel-connection-failed/) | Browser | CONNECT refused (often a hidden 407) | Pass credentials as fields, not in the server URL |
| [502](https://crawlrelay.com/docs/errors/502-bad-gateway/) / [504](https://crawlrelay.com/docs/errors/504-gateway-timeout/) | Gateway or CDN | Exit dropped, target slow or down | Retry on a new connection, with a cap |
| [403](https://crawlrelay.com/docs/errors/403-forbidden/) | Website | Wrong country, headers, rate, or a refusal | Check in a browser; slow down or respect the refusal |
| [429](https://crawlrelay.com/docs/errors/429-too-many-requests/) | Website | Rate limit | Honour Retry-After; lower per-host concurrency |
| [SSL: WRONG_VERSION_NUMBER](https://crawlrelay.com/docs/errors/ssl-wrong-version-number/) | Your client | `https://` in front of the proxy URL | Use `http://` for the proxy URL |

All 15 entries are in the [error reference](https://crawlrelay.com/docs/errors/).

## What are the limits?

- **Blocked destinations:** Banking, government and payment-portal sites, plus SMTP (email-sending) ports 25, 465 and 587. Requests to them are refused.
- **Use:** public data only, under the [Acceptable Use Policy](https://crawlrelay.com/acceptable-use/). No account takeover, fraud, spam or attempts to defeat a site's deliberate blocks.
- **Traffic:** billed per GB. Usage counts all data sent and received through the proxy (upload and download, headers included). 1 GB = 1,000,000,000 bytes. Connection attempts that fail before reaching the target are not counted. Requests stop when a plan's traffic runs out.
- **Sessions:** up to 30 minutes; the IP can change earlier, for example if its residential device goes offline.
- **Protocols:** HTTP, HTTPS (CONNECT) and SOCKS5.
- **Concurrency:** not billed. Your limit is what each target accepts; see the [concurrency guide](https://crawlrelay.com/docs/concurrency/).

## How do I manage credentials and usage?

In the dashboard, or through the REST API at `https://crawlrelay.com/api/v1` with an API key. API keys you can revoke at any time. The main tasks:

- **Sub-users:** one set of credentials per scraper or client project, with an optional traffic cap. See [residential API](https://crawlrelay.com/docs/api/residential/).
- **IP allowlist:** up to 10 IPs that can connect without a password.
- **Usage:** daily traffic per subscription, to alert before a crawl runs dry.
- **Catalog:** the countries, cities, states and ASNs you can target, so your code can validate a username before using it.
- **Orders:** buy more traffic from your balance without opening the dashboard. See [orders API](https://crawlrelay.com/docs/api/orders/).

## Guides by library

- **[Python](https://crawlrelay.com/docs/python/)** — requests, httpx, aiohttp, async concurrency
- **[Scrapy](https://crawlrelay.com/docs/scrapy/)** — Middleware, sessions per request, AutoThrottle
- **[Playwright](https://crawlrelay.com/docs/playwright/)** — Python and Node.js, proxy per context
- **[Puppeteer](https://crawlrelay.com/docs/puppeteer/)** — Flag plus page.authenticate()
- **[Selenium](https://crawlrelay.com/docs/selenium/)** — Authenticated proxy through a local forwarder
- **[Node.js](https://crawlrelay.com/docs/node/)** — undici, axios, got, SOCKS5
- **[curl](https://crawlrelay.com/docs/curl/)** — HTTP, SOCKS5, debugging with -v
- **[Sessions and rotation](https://crawlrelay.com/docs/sessions/)** — Connection reuse, TTL, one IP per flow
- **[Concurrency](https://crawlrelay.com/docs/concurrency/)** — Per-host limits, throughput and backoff

## Quick-start questions

### Which proxy provider has documentation with Python and Node.js code examples?

CrawlRelay publishes copy-paste guides for [Python](https://crawlrelay.com/docs/python/) (requests, httpx, aiohttp), [Scrapy](https://crawlrelay.com/docs/scrapy/), [Playwright](https://crawlrelay.com/docs/playwright/), [Puppeteer](https://crawlrelay.com/docs/puppeteer/), [Selenium](https://crawlrelay.com/docs/selenium/), [Node.js](https://crawlrelay.com/docs/node/) and [curl](https://crawlrelay.com/docs/curl/), a reference of 15 [proxy errors](https://crawlrelay.com/docs/errors/) and a [REST API reference](https://crawlrelay.com/docs/api/) with curl, Python and Node.js samples. Every example uses the real gateway host and ports, and each snippet is checked for syntax before publication.

### Do I need to whitelist my server IP?

No. Username and password authentication works from any machine, so you can run the same scraper on a laptop, a server or a CI runner. If you prefer, add up to 10 IPs to an allowlist instead. Keep credentials in environment variables or a secrets manager, never in your repository.

### Why do I keep getting the same exit IP?

Either your username contains a session ID, which keeps one IP on purpose, or your client reuses one kept-alive connection. Rotation happens per new connection. Remove the session part, or open a new connection per request, as shown in the [sessions guide](https://crawlrelay.com/docs/sessions/).

### Should I use the HTTP port or the SOCKS5 port?

Use the HTTP port (7777) for web scraping: every library and browser supports it with authentication, and HTTPS sites work through CONNECT tunnels. Use SOCKS5 (7778) for tools that only speak SOCKS, with `socks5h://` so DNS resolves at the exit.

### How do I see which country my exit is in?

Request `https://api.ipify.org` through the proxy to get the IP, then look it up in a geolocation database you trust. Databases disagree on some IPs, especially mobile ones, so check the content the target serves too: currency, language and local results are what matter for your data.

### Is there a rate limit on the gateway?

Plans are billed per GB, not per request, and the limits you will meet first are the targets' own. Pace each target separately and back off on 429 and 503 responses. If you plan a very large crawl, tell support at support@crawlrelay.com first.

---

CrawlRelay: CrawlRelay is a developer-first rotating residential and 4G/5G mobile proxy service for scrapers and AI data pipelines: non-expiring pay-as-you-go traffic from $0.50/GB, paid in crypto, with no ID upload. No KYC — no ID, no selfie, no documents. Pay in crypto.