Spotted something off?Report on Discord
api reference
sessions.create
Start a persistent browser session that retains cookies and reduces repeated setup work across multi-step browser workflows.
Updated May 30, 2025
Start a persistent browser session that retains cookies, speeds up requests, and reduces repeated setup work across multi-step browser workflows.
A session remains active for 200 seconds after the last request. After that, it is automatically destroyed — or end it early with sessions.destroy. For state that must persist beyond a single session, use a persistent profile instead.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
session |
string | No | Custom session ID. If not set, a random UUID is generated. |
proxy |
string | No | Use a custom proxy. Supports http://, socks4://, or socks5:// with authentication. Example: "http://username:[email protected]:8888". Default: built-in rotating proxies from random countries — pin one with proxyCountry. |
whitelistedDomains |
array | No | Allow requests to specified external domains. Example: ["probot.io", "google.com"]. Useful for loading assets from third-party domains. |
datacenter |
boolean | No | Set to true to use a datacenter IP instead of a residential IP. Datacenter IPs offer higher speed and stability, but lower anonymity. |
browser |
array | No | Define the browser type and version range. Options: chrome, firefox, safari. Example: [{ "name": "chrome", "minVersion": 116, "maxVersion": 117 }]. |
operatingSystem |
array | No | Specify OS options. Options: windows, macos, linux, android, ios. Example: ["windows", "linux"]. |
device |
array | No | Choose device type. Options: desktop, mobile. Example: ["desktop", "mobile"]. |
Why Use sessions.create
- Speed: Reuses the same browser instance across multiple requests.
- Persistence: Retains cookies and session data until explicitly destroyed.
- Convenience: Reuses cookies and browser state across requests.
Request
bash6 lines
Want to run this request directly in your browser?to try it live with your own API key.
Response
json12 lines
Related concepts
Go deeper in the Scrappey knowledge base:
- Stateful web scraping — reusing cookies and state across requests
- Session cookie — the cookie that ties a session together