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 session ID will be routed through the same exit IP for the duration of the session. To get a new IP, simply change the session ID.
  • 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.
  • 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.
  • 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 session ID.

​
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-time-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.