Session API

The Session object manages shared configuration across multiple Page, Dataset, Crawl, and Watch operations. It centralizes headers, cookies, proxies, and rate limits.

5 min read Updated July 2026

Python Usage

session.py
python
1from crawlingo import Session, Page, Dataset
2
3session = Session()
4session.headers({
5 "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0",
6 "Accept-Language": "en-US,en;q=0.9"
7})
8session.cookies({"session_id": "abc123"})
9session.proxy("http://proxy.example.com:8080")
10session.rate_limit(5.0) # 5 requests/second per host
11session.timeout(30) # 30 second timeout
12session.auto_match(True) # Enable self-healing selectors
13session.fetcher_tier("stealthy") # "standard" or "stealthy"
14session.browser_profile("chrome") # "chrome", "firefox", "safari"
15
16# Use across multiple operations
17page = Page("https://example.com", session=session)
18dataset = Dataset("https://shop.example.com", session=session)

Node.js Usage

session.ts
typescript
1import { Session, Page } from 'crawlingo';
2
3const session = new Session();
4session.headers({ 'User-Agent': 'MyBot/1.0' });
5session.rateLimit(5.0);
6session.timeout(30);
7session.autoMatch(true);
8
9const page = await Page.create('https://example.com', session);

Session Methods

MethodParametersDescription
headers(dict)Header key-value pairsSet default HTTP request headers
cookies(dict)Cookie key-value pairsSet default cookies for requests
proxy(url)Proxy URL stringSet single HTTP/HTTPS proxy
proxy_pool(list)List of proxy URLsEnable round-robin proxy pool rotation
rate_limit(rps)Requests per second (float)Per-host rate limiting (0 = disabled)
timeout(secs)Seconds (int)Set request timeout
auto_match(bool)BooleanEnable self-healing selector recovery
fetcher_tier(tier)"standard" | "stealthy"TLS fingerprint emulation level

Configuration Precedence

Settings are resolved in the following priority order (later steps override earlier ones):

  1. TOML configuration file (crawlingo.toml)
  2. Environment variables (CRAWLINGO_*)
  3. Session constructor options
  4. Session method calls (e.g. session.rate_limit(5.0))
  5. Per-request explicit parameter overrides