Session Management

Sticky Sessions

Maintain the same proxy IP address across multiple requests for up to 60 minutes. Essential for login flows, checkout processes, form submissions, and any multi-step workflow that requires IP consistency.

How Sticky Sessions Work

When you include a sessid parameter in your proxy username, ZentisLabs pins that session to a specific IP address. All subsequent requests with the same session ID will use the same IP for the duration of the TTL (time-to-live).

1️⃣

First Request

IP assigned and pinned to your session ID

2️⃣

Subsequent Requests

Same session ID → same IP address

3️⃣

TTL Expires

After TTL, new IP assigned on next request

Proxy Type	Max TTL	Default TTL
Residential	60 minutes	10 minutes
Mobile	60 minutes	10 minutes
ISP	Unlimited	Permanent
Datacenter	60 minutes	10 minutes

Basic Sticky Session

bash

# Add sessid parameter to maintain same IP
SESSION="my-session-001"

# Request 1 — IP is assigned
curl -x "http://customer-USERNAME-cc-US-sessid-$SESSION:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# Request 2 — same IP used
curl -x "http://customer-USERNAME-cc-US-sessid-$SESSION:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# Both requests show the same origin IP

python

import requests

SESSION_ID = "checkout-flow-42"
proxy = f"http://customer-USERNAME-cc-US-sessid-{SESSION_ID}:PASSWORD@gate.zentislabs.com:8080"
proxies = {"http": proxy, "https": proxy}

# Use requests.Session for connection reuse
session = requests.Session()
session.proxies = proxies

# All requests use the same proxy IP
r1 = session.get("https://example.com/login")
r2 = session.post("https://example.com/add-to-cart", json={"item": "SKU-123"})
r3 = session.post("https://example.com/checkout")

# Verify same IP
ip1 = session.get("https://httpbin.org/ip").json()["origin"]
ip2 = session.get("https://httpbin.org/ip").json()["origin"]
assert ip1 == ip2, "IP should be the same"
print(f"Both requests used IP: {ip1}")

typescript

import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const sessionId = "user-session-42";
const agent = new HttpsProxyAgent(
  `http://customer-USERNAME-cc-US-sessid-${sessionId}:PASSWORD@gate.zentislabs.com:8080`
);

// All requests use the same IP
const [r1, r2, r3] = await Promise.all([
  axios.get("https://httpbin.org/ip", { httpsAgent: agent }),
  axios.get("https://httpbin.org/ip", { httpsAgent: agent }),
  axios.get("https://httpbin.org/ip", { httpsAgent: agent }),
]);

console.log(r1.data.origin, r2.data.origin, r3.data.origin);
// All three show the same IP

Advanced Patterns

Session per Account

Assign a unique session per account/user to maintain consistent IP identity.

python

import requests
import hashlib

def get_proxy_for_account(account_id: str) -> dict:
    """Create a unique sticky session per account."""
    session_id = hashlib.md5(account_id.encode()).hexdigest()[:12]
    proxy = f"http://customer-USERNAME-cc-US-sessid-{session_id}:PASSWORD@gate.zentislabs.com:8080"
    return {"http": proxy, "https": proxy}

# Each account always gets the same IP
accounts = ["user_alice", "user_bob", "user_charlie"]
for account in accounts:
    proxies = get_proxy_for_account(account)
    r = requests.get("https://httpbin.org/ip", proxies=proxies)
    print(f"{account}: {r.json()['origin']}")

Session with Custom TTL

bash

# Set custom session TTL (in seconds)
# sesstime-300 = 5-minute TTL
curl -x "http://customer-USERNAME-cc-US-sessid-abc123-sesstime-300:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# sesstime-1800 = 30-minute TTL (maximum for residential)
curl -x "http://customer-USERNAME-cc-US-sessid-abc123-sesstime-1800:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

Session Rotation Strategy

python

import requests
import time

def scrape_with_session_rotation(urls: list[str], batch_size: int = 50):
    """Rotate session ID every batch_size requests to get fresh IPs."""
    results = []
    for i, url in enumerate(urls):
        session_id = f"batch-{i // batch_size}"
        proxy = f"http://customer-USERNAME-cc-US-sessid-{session_id}:PASSWORD@gate.zentislabs.com:8080"
        proxies = {"http": proxy, "https": proxy}
        
        try:
            r = requests.get(url, proxies=proxies, timeout=30)
            results.append(r.json())
        except requests.RequestException as e:
            print(f"Failed {url}: {e}")
    
    return results

urls = [f"https://example.com/page/{i}" for i in range(200)]
data = scrape_with_session_rotation(urls)

Best Practices

Use descriptive session IDs

Include context in your session ID (e.g., 'checkout-user42') for easier debugging and monitoring.

Don't reuse expired sessions

After TTL expires, use a new session ID. Reusing an expired ID may assign a different IP.

Match session to workflow

Use one session per workflow (login→checkout). Don't share sessions across unrelated tasks.

Monitor session health

Track success rates per session. If a session's IP gets blocked, create a new session immediately.

Set appropriate TTL

Use the shortest TTL that covers your workflow. Longer TTLs hold IPs from the pool longer.

Handle session expiry gracefully

Implement retry logic that creates a new session if the current one returns errors.

Troubleshooting

Session returns different IPs

The session likely expired. Check the TTL and create a new session. Also verify the sessid parameter is identical across requests.

Session IP is blocked

Create a new session with a different ID. The new session will be assigned a fresh IP from the pool.

Session drops mid-workflow

Increase sesstime parameter or implement retry logic that detects IP changes and re-creates the session.

Country Targeting

Combine sticky sessions with precise geo-targeting.

Error Handling

Handle errors, retries, and failover strategies.

Session Management

Sticky Sessions

How Sticky Sessions Work

1️⃣

First Request

IP assigned and pinned to your session ID

2️⃣

Subsequent Requests

Same session ID → same IP address

3️⃣

TTL Expires

After TTL, new IP assigned on next request

Proxy Type	Max TTL	Default TTL
Residential	60 minutes	10 minutes
Mobile	60 minutes	10 minutes
ISP	Unlimited	Permanent
Datacenter	60 minutes	10 minutes

Basic Sticky Session

bash

# Add sessid parameter to maintain same IP
SESSION="my-session-001"

# Request 1 — IP is assigned
curl -x "http://customer-USERNAME-cc-US-sessid-$SESSION:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# Request 2 — same IP used
curl -x "http://customer-USERNAME-cc-US-sessid-$SESSION:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# Both requests show the same origin IP

python

import requests

SESSION_ID = "checkout-flow-42"
proxy = f"http://customer-USERNAME-cc-US-sessid-{SESSION_ID}:PASSWORD@gate.zentislabs.com:8080"
proxies = {"http": proxy, "https": proxy}

# Use requests.Session for connection reuse
session = requests.Session()
session.proxies = proxies

# All requests use the same proxy IP
r1 = session.get("https://example.com/login")
r2 = session.post("https://example.com/add-to-cart", json={"item": "SKU-123"})
r3 = session.post("https://example.com/checkout")

# Verify same IP
ip1 = session.get("https://httpbin.org/ip").json()["origin"]
ip2 = session.get("https://httpbin.org/ip").json()["origin"]
assert ip1 == ip2, "IP should be the same"
print(f"Both requests used IP: {ip1}")

typescript

import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const sessionId = "user-session-42";
const agent = new HttpsProxyAgent(
  `http://customer-USERNAME-cc-US-sessid-${sessionId}:PASSWORD@gate.zentislabs.com:8080`
);

// All requests use the same IP
const [r1, r2, r3] = await Promise.all([
  axios.get("https://httpbin.org/ip", { httpsAgent: agent }),
  axios.get("https://httpbin.org/ip", { httpsAgent: agent }),
  axios.get("https://httpbin.org/ip", { httpsAgent: agent }),
]);

console.log(r1.data.origin, r2.data.origin, r3.data.origin);
// All three show the same IP

Advanced Patterns

Session per Account

Assign a unique session per account/user to maintain consistent IP identity.

python

import requests
import hashlib

def get_proxy_for_account(account_id: str) -> dict:
    """Create a unique sticky session per account."""
    session_id = hashlib.md5(account_id.encode()).hexdigest()[:12]
    proxy = f"http://customer-USERNAME-cc-US-sessid-{session_id}:PASSWORD@gate.zentislabs.com:8080"
    return {"http": proxy, "https": proxy}

# Each account always gets the same IP
accounts = ["user_alice", "user_bob", "user_charlie"]
for account in accounts:
    proxies = get_proxy_for_account(account)
    r = requests.get("https://httpbin.org/ip", proxies=proxies)
    print(f"{account}: {r.json()['origin']}")

Session with Custom TTL

bash

# Set custom session TTL (in seconds)
# sesstime-300 = 5-minute TTL
curl -x "http://customer-USERNAME-cc-US-sessid-abc123-sesstime-300:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

# sesstime-1800 = 30-minute TTL (maximum for residential)
curl -x "http://customer-USERNAME-cc-US-sessid-abc123-sesstime-1800:PASSWORD@gate.zentislabs.com:8080" \
  "https://httpbin.org/ip"

Session Rotation Strategy

python

import requests
import time

def scrape_with_session_rotation(urls: list[str], batch_size: int = 50):
    """Rotate session ID every batch_size requests to get fresh IPs."""
    results = []
    for i, url in enumerate(urls):
        session_id = f"batch-{i // batch_size}"
        proxy = f"http://customer-USERNAME-cc-US-sessid-{session_id}:PASSWORD@gate.zentislabs.com:8080"
        proxies = {"http": proxy, "https": proxy}
        
        try:
            r = requests.get(url, proxies=proxies, timeout=30)
            results.append(r.json())
        except requests.RequestException as e:
            print(f"Failed {url}: {e}")
    
    return results

urls = [f"https://example.com/page/{i}" for i in range(200)]
data = scrape_with_session_rotation(urls)

Best Practices

Use descriptive session IDs

Include context in your session ID (e.g., 'checkout-user42') for easier debugging and monitoring.

Don't reuse expired sessions

After TTL expires, use a new session ID. Reusing an expired ID may assign a different IP.

Match session to workflow

Use one session per workflow (login→checkout). Don't share sessions across unrelated tasks.

Monitor session health

Track success rates per session. If a session's IP gets blocked, create a new session immediately.

Set appropriate TTL

Use the shortest TTL that covers your workflow. Longer TTLs hold IPs from the pool longer.

Handle session expiry gracefully

Implement retry logic that creates a new session if the current one returns errors.

Troubleshooting

Session returns different IPs

The session likely expired. Check the TTL and create a new session. Also verify the sessid parameter is identical across requests.

Session IP is blocked

Create a new session with a different ID. The new session will be assigned a fresh IP from the pool.

Session drops mid-workflow

Increase sesstime parameter or implement retry logic that detects IP changes and re-creates the session.

Country Targeting

Combine sticky sessions with precise geo-targeting.

Error Handling

Handle errors, retries, and failover strategies.