Skip to main content
Session control allows you to manage the lifecycle of your proxy’s IP address. By default, every request you make gets a new, random IP address from our pool (per-request rotation). However, for many tasks, you need to maintain the same IP across multiple requests. This is called a “sticky session”. You control this behavior by adding session parameters to your proxy’s username.

​
Session Types

Rotating IP (Default)

Behavior: You get a new IP address on every single request.
Use Case: Ideal for large-scale scraping tasks where you need maximum diversity of IPs to avoid rate limits and blocks.
How to use: Send requests with your base username, without any session parameters.

Sticky IP (Sticky Session)

Behavior: You get a single IP address and can reuse it for a specific period.
Use Case: Essential for any multi-step workflow on a website, such as logging in, adding items to a cart, or navigating through paginated results.
How to use: Add the -session parameter to your username.

​
Session Control Parameters

These parameters work together to give you full control over your sticky sessions.

​
Session ID (-session)

This is the primary parameter for enabling a sticky session.
  • Format: -session-[id]
  • Value: Any alphanumeric string you choose. This string is your unique identifier for a session.
  • Dependencies: None.
  • How it works: All requests sent with the same sessionID will be routed through the same exit IP for the duration of the session. To get a new IP, simply change the sessionID.
  • Example Usernames:
    • ...-my-scraper-session-user123 (gets IP A)
    • ...-my-scraper-session-user123 (still gets IP A)
    • ...-my-scraper-session-user456 (gets a new IP, IP B)

​
Session Time (-time)

By default, a sticky session lasts for 10 minutes. The -time parameter allows you to change this duration.
  • Format: -time-[minutes]
  • Value: A whole number between 1 and 1440 (for 24 hours).
  • Dependencies: Must be used together with a -session parameter.
  • Example Username: ...-my-scraper-session-user123-time-30
  • Result: The sticky session for user123 will now last for 30 minutes instead of the default 10. The timer resets every time a new request is made with this session ID.
  • Error Case: Using -time-30 without -session will result in an error.
Important Note on Session Reliability: The session duration is a request, not a 100% guarantee. Due to the dynamic nature of residential networks, a peer device can go offline at any time. If the IP for your session becomes unavailable, our system will automatically assign you a new IP on your next request with the same sessionID.

​
Strict Session (-const)

This parameter changes the behavior of the gateway when a session IP goes offline.
  • Format: -const (this is a flag, it has no value).
  • Dependencies: Must be used together with a -session parameter.
  • Default Behavior (without -const): If your session IP goes offline, we automatically assign a new IP to your session. This ensures your scraper continues working.
  • Behavior with -const: If your session IP goes offline, we do not assign a replacement. Instead, your request will fail with a 502 Bad Gateway error and an X-2extract-Error: Session IP is offline header.
  • Use Case: Use this only when your workflow is critically dependent on using the exact same IP from start to finish, and you would rather have the process fail than continue with a new IP.
  • Example Username: ...-my-scraper-session-user123-stime-60-const

​
Which Session Type Should I Use?

Choose the best session type for your specific task. All parameters can be combined with any valid geo-targeting.
If your goal is…Recommended Parameter(s)Example UsernameWhy it works
Maximum Anonymity & Scraping Simple Pages
(e.g., collecting product prices from multiple pages)		(None - use default behavior)...-proxy-myproject-country-deBy default, you get a new IP for every single request. This makes it extremely difficult for the target website to track you as a single user.
Multi-Step Actions & Logins
(e.g., logging into an account, filling a form, navigating a cart)		-session-[your_id]...-proxy-myproject-session-user123Using a session ID guarantees that you will keep the same IP address for a sequence of requests, making you look like a regular user navigating the site.
Long-Term Data Collection from a Single IP
(e.g., monitoring a specific social media profile for an hour)		-session-[your_id] -time-[minutes]...-proxy-myproject-session-task456-time-60Adding the -time parameter extends the default 10-minute session lifetime. You can request to keep the same IP for up to 24 hours (1440 minutes).
High-Security Tasks Where IP Change is Unacceptable
(e.g., managing a sensitive online account where a sudden IP change could trigger a security alert)		-session-[your_id] -const...-proxy-myproject-session-secure-constThe -const flag ensures that if your assigned session IP goes offline, your request will fail with an error instead of automatically getting a new IP. This prevents accidental IP exposure.