​
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 60 minutesDefault: 15 minutes30, 60

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 defaults to 15 minutes but can be customized using the sessionttl parameter. 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

  • When a session identifier is specified and found the server will perform a request via the same node unless:

    • TTL is expired.

    • The request limit per minute for the node is exceeded.

    • The node has gone offline.

  • 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 the new node.Additional parameters

KeyValue
sessionmodestrict, flex

By default, when a sticky session fails, our algorithm attempts to find a new node to complete the request, attaching a new IP address to the sticky session. This behavior can be overwritten by specifying sessionmode-flex.

Example of using undefined sessionmode, which defaults to sessionmode-strict:

curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace

Example with sessionmode-strict explicitly defined:

curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123-sessionmode-strict:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace

Alternatively, a sticky session can persist through an error by using sessionmode-flex, though this may increase error rate.

Attention: The max number of errors is 15 until a new node is assigned to a sticky session.

Example with sessionmode-flex:

curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123-sessionmode-flex:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace

​
Known issues

When session is specified without geotargeting or use of one of our regional endpoints, the request may get cross routed, causing different IPs to be called during a sticky session depending on which server handles the request.

Workarounds:

  1. Use regional endpoints https://us-network.joinmassive.com/ or https://eu-network.joinmassive.com/
curl -x https://us-network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
  1. Use geotargeting
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-country-US-session-123:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
GeotargetingDevice-type targeting