# Sessions

***

### Overview

Sessions determine how long you keep the same IP address. This is crucial for:

* Maintaining login states
* Multi-page scraping workflows
* Avoiding detection patterns

***

### Session Types

#### Rotating Sessions

Get a **new IP address with each request**.

```json
{
  "session_type": "rotating"
}
```

**Best for:**

* High-volume scraping
* Anonymous browsing
* When you don't need IP persistence

**How it works:**

```
Request 1 → IP: 192.168.1.1
Request 2 → IP: 192.168.1.2
Request 3 → IP: 192.168.1.3
```

***

#### Sticky Sessions

**Keep the same IP** for the duration of your session.

```json
{
  "session_type": "sticky",
  "session_id": "123456"
}
```

**Best for:**

* Login flows
* Shopping cart sessions
* Multi-step processes
* Form submissions

**How it works:**

```
Request 1 (session: 123456) → IP: 192.168.1.1
Request 2 (session: 123456) → IP: 192.168.1.1  ← Same IP
Request 3 (session: 123456) → IP: 192.168.1.1  ← Same IP
Request 4 (session: 789012) → IP: 192.168.1.2  ← Different session = new IP
```

{% hint style="info" %}
For **Residential** and **Unlimited Residential** proxies, session duration may vary depending on the peer availability. The same session ID will attempt to maintain the same IP as long as the peer is available.
{% endhint %}

***

### Using Sessions in API

#### Generate Sticky Proxies

```bash
POST /proxies/generate
```

```json
{
  "sub_user_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "format": "{ip}:{port}:{user}:{pass}",
  "session_type": "sticky",
  "session_duration": 10,
  "quantity": 5
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "proxies": [
      "res.plainproxies.com:8080:user-session-abc123-lifetime-600:password",
      "res.plainproxies.com:8080:user-session-def456-lifetime-600:password"
    ]
  }
}
```

Each proxy string contains a unique session ID that maintains the sticky session.

***

### Session IDs and Lifetime

Session IDs must be **numeric values from 000000 to 999999**. You can also specify a **lifetime** in seconds (maximum 86400 seconds = 24 hours).

#### Username Format

```
username-session-123456-lifetime-86400:password
```

| Parameter  | Value               | Description                                |
| ---------- | ------------------- | ------------------------------------------ |
| `session`  | `000000` - `999999` | Unique session identifier                  |
| `lifetime` | `1` - `86400`       | Session duration in seconds (max 24 hours) |

#### Examples

| Lifetime   | Seconds | Username Example                     |
| ---------- | ------- | ------------------------------------ |
| 10 minutes | 600     | `user-session-123456-lifetime-600`   |
| 1 hour     | 3600    | `user-session-123456-lifetime-3600`  |
| 24 hours   | 86400   | `user-session-123456-lifetime-86400` |

{% hint style="info" %}
For **Residential** and **Unlimited Residential** proxies, the actual session duration may vary depending on peer availability, even within the specified lifetime.
{% endhint %}

***

### Session in Username

You can control sessions via the proxy username:

#### Rotating

```
username:password
```

#### Sticky with Lifetime

```
username-session-123456-lifetime-3600:password
```

* **Session ID**: 6-digit number (000000 to 999999)
* **Lifetime**: Duration in seconds (max 86400 = 24 hours)

***

### Session Best Practices

#### 1. Use Unique Session IDs

For sticky sessions, each task should have a unique session ID:

```python
import random

session_id = str(random.randint(0, 999999)).zfill(6)
lifetime = 3600  # 1 hour
proxy_user = f"user-session-{session_id}-lifetime-{lifetime}"
```

#### 2. Match Session to Task

```python
# Login flow - use sticky
login_proxy = generate_proxy(session_type="sticky", duration=30)

# Scraping catalog - use rotating
scrape_proxy = generate_proxy(session_type="rotating")
```

#### 3. Handle Session Changes

```python
import random

def get_new_session_id():
    return str(random.randint(0, 999999)).zfill(6)

# When you need a new IP, generate a new session ID
current_session = get_new_session_id()
proxy_user = f"user-session-{current_session}-lifetime-86400"

# Later, when you need a different IP
new_session = get_new_session_id()
proxy_user = f"user-session-{new_session}-lifetime-86400"
```

***

### Supported Proxy Types

| Type                  | Rotating | Sticky |
| --------------------- | -------- | ------ |
| Datacenter            | ✅        | ✅      |
| Residential           | ✅        | ✅      |
| Unlimited Residential | ✅        | ✅      |
| IPv6                  | ✅        | ✅      |
| ISP                   | ✅        | ✅      |

All proxy types support both rotating and sticky sessions.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.plainproxies.com/concepts/sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.