Sessions
A session lets several requests act as the same visitor. Name one in options.session, and every request using that name shares:
- Cookies: what the site set (a login, a cart, a consent choice) is sent back next time.
- IP address: the proxy of the first request is kept, retries included.
- Identity: the fingerprint, or the User-Agent of the browser that opened the session.
It works across everything: start in one browser, continue in another, or without a browser at all.
"options": { "session": "my-login" }Log in with a browser, scrape without one
The demo login form needs JavaScript: a hidden field is filled by a script. Without a browser, logging in fails:
Actions
Data
Log in once with a browser instead:
Actions
Data
Then read the account page with plain, fast requests. The session cookie, IP and User-Agent are the browser's:
Actions
Data
Options
session accepts a name, an object, or true:
| Value | Meaning |
|---|---|
"my-login" | The session with this name, created if it doesn't exist. 1 to 64 letters, digits, _, - or . |
{ "id": "my-login", "ttl": 3600 } | The same, kept ttl seconds after its last use: 60 to 86400, default 1800 |
true | A new session with a random name, returned in the response |
A session expires when it hasn't been used for ttl seconds. Each request using it pushes that back.
The response
Each response says where the session stands:
"session": {
"id": "docs-demo",
"expires_at": "2026-10-19T14:32:10.000Z",
"proxy": { "source": "pool", "country": "FR" },
"fingerprint": null,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 …",
"cookies": 1
}GET /sessions/{id} returns the cookies themselves, to use them elsewhere. DELETE logs the session out.
What stays, what changes
| Kept from the session | To change it | |
|---|---|---|
| Cookies | Always. options.cookies are added to the session | DELETE /sessions/{id}, or another name |
| Proxy | The one that first got a page. Requests that don't mention proxy use it too | "proxy": false for one request without it |
| Fingerprint | Kept when the request allows it: no fingerprint without a browser, or a list containing it | "fingerprint": false |
| User-Agent | The browser's or the fingerprint's, for requests without a browser | A fingerprint, or a User-Agent header |
A browser always shows its own User-Agent: the session's is only reused without one.
Pages fetched with a session can be personal, so they are never cached. With cache_ttl set, a warning says so.
Sessions live in the server's memory: a restart ends them all.