Proxy API

Endpoint

# Username = your token + optional session/country qualifiers
# Password = blank

Basic usage

curl -x 'http://YOUR_TOKEN:@backconnect.crawlbase.com:9000' \
     'https://httpbin.org/ip'

import requests

proxies = {
    'http':  'http://YOUR_TOKEN:@backconnect.crawlbase.com:9000',
    'https': 'http://YOUR_TOKEN:@backconnect.crawlbase.com:9000',
}
res = requests.get('https://httpbin.org/ip', proxies=proxies)

Each request goes through a different residential IP by default - pure rotation.

Sticky sessions

To pin requests to a single IP, append a session ID to your username. The same session ID returns the same IP for ~30 minutes.

# Format: TOKEN-session-SESSION_ID
curl -x 'http://YOUR_TOKEN-session-checkout42:@backconnect.crawlbase.com:9000' \
     'https://shop.example.com/cart'

Country targeting

# Format: TOKEN-country-XX
curl -x 'http://YOUR_TOKEN-country-DE:@backconnect.crawlbase.com:9000' \
     'https://www.amazon.de'

# Combine: country + session
curl -x 'http://YOUR_TOKEN-country-DE-session-cart-1:@backconnect.crawlbase.com:9000' \
     'https://www.amazon.de/cart'

Username qualifiers

Reference of all available username modifiers, combined with hyphens.

Static IPs and geolocalization

When you need to keep the same exit IP across multiple requests - multi-step checkout flows, account login + scrape, anything that depends on the target site recognizing the same client - Backconnect can lock a static IP and hand back the port + session lifetime. The proxy then keeps that IP bound to your token as long as you keep using it inside the session window.

The static-IP endpoint is rate-limited to 1 request per 5 minutes per country (or 1 per 5 minutes overall if no country is specified). Cache the port your client receives - don't re-request on every crawl.

Get a static IP

Returns a port to use with proxy.crawlbase.com, plus the seconds the binding stays alive. The session timer auto-extends as long as you keep sending traffic through that port within the window.

curl 'https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN'

# Response
# { "port": 1234, "host": "proxy.crawlbase.com", "session_time": 10 }

Static IP from a specific country

Pass a 2-letter ISO 3166 country code (US, GB, DE, IT, RU, …) to pin the static IP to that geography. If no port is currently free in the requested country, the response carries an error - back off and retry against the country-bucket rate limit.

curl 'https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN&country=FR'

# Response
# { "port": 4551, "host": "proxy.crawlbase.com", "session_time": 10 }

IP whitelisting

Backconnect supports IP whitelisting - let your server's outbound IPs authenticate against the proxy without sending the token on every request. Useful for fixed-IP pipelines that don't want credentials in code, and the only way to use Backconnect from environments that can't pass a Proxy-Authorization header.

Three endpoints, all under /proxy/whitelist_ips, differentiated by HTTP method. Changes take up to 1 minute to propagate.

Add a whitelisted IP

curl -X POST 'https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123'

Remove a whitelisted IP

curl -X DELETE 'https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123'

View whitelisted IPs

Returns the current list of whitelisted IPs for your token, in JSON.

curl 'https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN'

Backconnect vs Smart AI Proxy