Skip to main content

​
Overview

By default, Nimble rotates to a new IP for every request. Session control lets you maintain the same IP across multiple requests or configure custom rotation intervals.

​
Session Types

Rotating (Default)

New IP for every request

Sticky Session

Same IP across multiple requests

Geo Session

Maintain geographic proximity and ISP consistency across rotations

​
Sticky Sessions

Maintain the same IP address across multiple requests by creating a session.

​
How It Works

  1. Add a session ID to your connection string
  2. All requests with the same session ID use the same IP
  3. Session remains active for 10 minutes after last request
  4. If the IP goes offline, a new IP is automatically assigned

​
Format

account-{accountName}-pipeline-{pipelineName}-session-{sessionId}

​
Session ID Requirements

  • Maximum 32 alphanumeric characters
  • Cannot include hyphens
  • No minimum length requirement
  • Use any arbitrary string

​
Example

curl -vvv -x http://account-accountName-pipeline-pipelineName-session-mysession123:[email protected]:7000 \
  https://ipinfo.io/json

# Make another request with the same session
curl -vvv -x http://account-accountName-pipeline-pipelineName-session-mysession123:[email protected]:7000 \
  https://example.com

​
Session Expiration

1

Active Session

Requests maintain the same IP while session is active
2

Inactivity Period

After last request, session stays alive for 10 minutes
3

Expiration

After 10 minutes of inactivity, IP is released and session expires
4

Renewal

Next request with same session ID gets a new IP

​
Combining with Geotargeting

Create sticky sessions with specific geographic targeting: 
curl -vvv -x http://account-accountName-pipeline-pipelineName-country-US-state-NY-session-mysession:[email protected]:7000 \
  https://ipinfo.io/json
This maintains a sticky session with a New York IP.

​
Configuration via Pipeline Settings

For IP allowlist authentication, configure rotation behavior in pipeline settings.

​
Rotation Options

OptionDescription
Every requestNew IP for each request (default)
1 minuteRotate IP every 1 minute
3 minutesRotate IP every 3 minutes
5 minutesRotate IP every 5 minutes
10 minutesRotate IP every 10 minutes
30 minutesRotate IP every 30 minutes

​
IP Replacement Options

Configure what happens when the current IP becomes unavailable:
OptionBehavior
Replace IPAutomatically assign any available IP
Same ASNReplace with IP from same ISP/ASN when possible
Fail requestReturn error instead of replacing IP

​
Configuration Methods

Configure through:
  • Nimble dashboard pipeline settings page
  • Admin API /account/pipelines endpoint

​
Geo-Sessions (Advanced)

For enhanced location consistency, use geo-sessions instead of regular sessions.

​
Key Differences

FeatureRegular SessionGeo-Session
IP consistencySame IP maintainedMay rotate within constraints
Location consistencyWaterfall: city -> state -> countryMax proximity - 15km radius
ASN/ISP consistencyNo guaranteeWhen Possible
Rotation sensitivityMediumLow (more stable)
PerformanceHighMedium

​
Format

account-{accountName}-pipeline-{pipelineName}-geosession-{sessionId}

​
Requirements

  • Session ID: 16-32 alphanumeric characters (minimum 16 characters)
  • Request timeout: Recommended 40+ seconds
  • Session persistence: Up to 10 days of inactivity
  • Availability: World-wide, optimized performance in US

​
Example

curl -vvv -x http://account-accountName-pipeline-pipelineName-country-US-geosession-mysession12345678:[email protected]:7000 \
  https://ipinfo.io/json
When to use Geo-sessions: Use geo-sessions for long, multi-step processes that need location stability (within 15km) and ASN consistency, such as simulating real user behavior or multi-page workflows.

​
Best Practices

Generate unique session IDs for different workflows to avoid conflicts
Use geo-sessions for multi-step processes requiring location consistency
Monitor session expiration and handle re-authentication when sessions expire
Configure fallback behavior in pipeline settings for IP replacement

​
Next Steps

Geotargeting

Combine sessions with geographic targeting

Response Codes

Handle session-related errors