> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2extract.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Session Control Parameters
> Learn how to manage IP rotation and create sticky sessions with custom durations using session control parameters.
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
**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.
**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.
| If your goal is... | Recommended Parameter(s) | Example Username | Why it works |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Maximum Anonymity & Scraping Simple Pages**
(e.g., collecting product prices from multiple pages) | (None - use default behavior) | `...-proxy-myproject-country-de` | By 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-user123` | Using 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-60` | Adding the `-time` parameter extends the default 10-minute session lifetime. |
| **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-const` | The `-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. |