​
Using sticky sessions

KeyValueTTLExamples
sessionAny unique identifier of up to 255 characters (regardless of character encoding); Massive will make best efforts to route requests in the same session to the same egress nodeDefault: 15 minutes (customizable with sessionttl)session42, 1234
sessionttlCustomizable session TTL in minutes, up to 240 minutesDefault: 15 minutes30, 60, 120, 240
You can inject a session identifier, like a unique representation of your app or active task, to specify that multiple requests should originate from a single egress node (if available): 
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-37:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace

​
Session TTL Behavior

  • Session TTL defaults to 15 minutes but can be customized using the sessionttl parameter up to 240 minutes (4 hours).
  • Important: Sessions use static TTL - they expire at creation time + TTL and are not extended by subsequent requests.
  • For example, to set the TTL to 30 minutes:
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-37-sessionttl-30:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace

​
Session Rotation

When a session identifier is specified and found, the server will perform a request via the same node unless:
  • TTL is expired (sessions expire exactly at creation time + TTL)
  • The request limit per minute for the node is exceeded
  • The node has gone offline
  • Error limit is reached (in flex mode)
If the session identifier is not found or the conditions above are not met, a new session is created with the specified ID and attached to a new node.

​
Session Modes

KeyValueDescription
sessionmodestrict, flexControls session behavior on errors

​
Flex Mode (Default)

By default, sessions operate in flex mode where sessions persist through errors up to a configurable limit. In this mode:
  • Sessions continue through errors up to the error limit (default: 15)
  • Error count resets to 0 on successful requests
  • Provides better IP stability during transient failures
  • May retry failing nodes multiple times
Note: The default error limit is 15. After 15 consecutive errors, a new node is assigned to the sticky session. You can customize this with the sessionerr parameter.
Example of using undefined sessionmode, which defaults to sessionmode-flex: 
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
Example with sessionmode-flex explicitly defined: 
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123-sessionmode-flex:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace

​
Strict Mode

Sessions can operate in strict mode where any error immediately invalidates the session and triggers rotation to a new node. This ensures clean IP rotation on failures but may change IPs more frequently. Example with sessionmode-strict: 
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123-sessionmode-strict:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace

​
Additional Parameters

KeyValueDescriptionDefault
sessionerrNumber (1-100)Maximum consecutive errors before rotation in flex mode15

​
Customizing Error Limit

In flex mode, you can customize how many errors are allowed before rotation: 
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123-sessionmode-flex-sessionerr-5:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
This example allows up to 5 consecutive errors before rotating to a new node.

​
Best Practices

  1. Plan TTL appropriately: Since sessions use static TTL (not extended by activity), set an appropriate duration for your use case
  2. Choose the right mode: Default flex mode provides IP stability; use strict mode if you need immediate rotation on any error
  3. Monitor error rates: Adjust sessionerr based on your tolerance for retries (default is 15)
  4. Session ID naming: Use descriptive session IDs to help with debugging and monitoring