crawlbaseDocs
Log in

Proxy API

A residential proxy network with sticky sessions and a flat single-port endpoint. Use it when Smart AI Proxy isn't flexible enough - direct access to the IP pool with rotation under your control.

Migrate to Smart AI Proxy

Faster routing, AI-driven ban avoidance, fewer config knobs. Proxy Backconnect is deprecated but existing integrations continue to work - no shutdown is scheduled.

Endpoint

PROXYproxy.crawlbase.com:9000
# Username = your token + optional session/country qualifiers
# Password = blank

Basic usage

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

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

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:@proxy.crawlbase.com:9000' \
     'https://shop.example.com/cart'
import requests

# Format: TOKEN-session-SESSION_ID
proxies = {
    'http':  'http://YOUR_TOKEN-session-checkout42:@proxy.crawlbase.com:9000',
    'https': 'http://YOUR_TOKEN-session-checkout42:@proxy.crawlbase.com:9000',
}
res = requests.get('https://shop.example.com/cart', proxies=proxies)
print(res.text)
const { fetch, ProxyAgent } = require('undici');

// Format: TOKEN-session-SESSION_ID
const dispatcher = new ProxyAgent('http://YOUR_TOKEN-session-checkout42:@proxy.crawlbase.com:9000');
const res = await fetch('https://shop.example.com/cart', { dispatcher });
console.log(await res.text());
require 'net/http'

# Format: TOKEN-session-SESSION_ID
uri = URI('https://shop.example.com/cart')
http = Net::HTTP.new(uri.host, uri.port, 'proxy.crawlbase.com', 9000, 'YOUR_TOKEN-session-checkout42', '')
http.use_ssl = true
puts http.get(uri.request_uri).body

Country targeting

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

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

# Format: TOKEN-country-XX
proxies = {
    'http':  'http://YOUR_TOKEN-country-DE:@proxy.crawlbase.com:9000',
    'https': 'http://YOUR_TOKEN-country-DE:@proxy.crawlbase.com:9000',
}
res = requests.get('https://www.amazon.de', proxies=proxies)
print(res.text)

# Combine: country + session
proxies = {
    'http':  'http://YOUR_TOKEN-country-DE-session-cart-1:@proxy.crawlbase.com:9000',
    'https': 'http://YOUR_TOKEN-country-DE-session-cart-1:@proxy.crawlbase.com:9000',
}
res = requests.get('https://www.amazon.de/cart', proxies=proxies)
print(res.text)
const { fetch, ProxyAgent } = require('undici');

// Format: TOKEN-country-XX
const country = new ProxyAgent('http://YOUR_TOKEN-country-DE:@proxy.crawlbase.com:9000');
const home = await fetch('https://www.amazon.de', { dispatcher: country });
console.log(await home.text());

// Combine: country + session
const session = new ProxyAgent('http://YOUR_TOKEN-country-DE-session-cart-1:@proxy.crawlbase.com:9000');
const cart = await fetch('https://www.amazon.de/cart', { dispatcher: session });
console.log(await cart.text());
require 'net/http'

def fetch(url, user)
  uri = URI(url)
  http = Net::HTTP.new(uri.host, uri.port, 'proxy.crawlbase.com', 9000, user, '')
  http.use_ssl = true
  http.get(uri.request_uri).body
end

# Format: TOKEN-country-XX
puts fetch('https://www.amazon.de', 'YOUR_TOKEN-country-DE')

# Combine: country + session
puts fetch('https://www.amazon.de/cart', 'YOUR_TOKEN-country-DE-session-cart-1')

Username qualifiers

Reference of all available username modifiers, combined with hyphens.

FormatEffect
TOKENDefault - random IP per request
TOKEN-country-XXIPs from country XX (ISO 3166)
TOKEN-session-NAMESticky to one IP for ~30 min
TOKEN-country-XX-session-NAMESticky session within a country

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.

Plan-gated feature

Static IPs and country targeting may not be available on every Backconnect plan, and country availability varies by tier. If you get an unauthorized response, check your plan or contact support before retrying.

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.

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

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

res = requests.get('https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN')
print(res.json())
const res = await fetch('https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN');
console.log(await res.json());
require 'net/http'

puts Net::HTTP.get(URI('https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN'))

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 }
import requests

res = requests.get('https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN&country=FR')
print(res.json())
const res = await fetch('https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN&country=FR');
console.log(await res.json());
require 'net/http'

puts Net::HTTP.get(URI('https://api.crawlbase.com/proxy/static?token=YOUR_TOKEN&country=FR'))

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.

Plan-gated feature

Whitelist management may not be available on every plan, and a per-plan cap limits how many IPs can be whitelisted at once. An unauthorized response means your tier doesn't include the feature; contact support to upgrade.

Add a whitelisted IP

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

res = requests.post('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123')
print(res.text)
const res = await fetch('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123', {
  method: 'POST',
});
console.log(await res.text());
require 'net/http'

res = Net::HTTP.post(URI('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123'), nil)
puts res.body

Remove a whitelisted IP

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

res = requests.delete('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123')
print(res.text)
const res = await fetch('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123', {
  method: 'DELETE',
});
console.log(await res.text());
require 'net/http'

uri = URI('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN&ip=123.123.123.123')
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.delete(uri.request_uri) }
puts res.body

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'
import requests

res = requests.get('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN')
print(res.json())
const res = await fetch('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN');
console.log(await res.json());
require 'net/http'

puts Net::HTTP.get(URI('https://api.crawlbase.com/proxy/whitelist_ips?token=YOUR_TOKEN'))

Backconnect vs Smart AI Proxy

Smart AI ProxyBackconnect
Use caseEasy mode - auto-routing, anti-bot bypassDirect IP pool access, custom rotation
JS renderingAvailableNo (raw proxy)
Auto-retryYesNo - handle yourself
Sticky sessionsVia headerVia username
Best forMost usersCustom scrapers, network research
Pick Smart AI Proxy first

Backconnect is the lower-level tool. If you don't have a specific reason to use it, Smart AI Proxy gives better results with less work.