In a previous article, Making Any Scraper Work with Sticky Proxies, we discussed how ProxyMapService maps local ports to independent sticky proxy sessions.
Each local port automatically receives its own session ID and keeps it for the configured StickyProxyLifetime. This allows applications that only support simple IP:PORT proxies to work with modern session-based proxy providers.
Until now, session management in ProxyMapService was completely automatic. While this works well for many use cases, some applications need direct control over when sessions are created, rotated, or discarded.
The latest version of ProxyMapService introduces a Session API that allows applications and scripts to inspect, reset, and create sessions on demand.
How sessions work
Assume the following configuration:
{
"Listen": {
"PortRange": {
"Start": 10201,
"End": 10300
},
"StickyProxyLifetime": 10
}
}When traffic is sent through port 10201, ProxyMapService generates a session ID:
10201 → session LZpmRqduAll requests made through this port will use the same sticky session until it expires.
The new Session API exposes this information and allows manual control over the session lifecycle.
Enabling Session API
For security and compatibility reasons, Session API is disabled by default.
To enable it, add the following section to your appsettings.json:
{
"SessionAPI": {
"Enabled": true,
"Domain": "portmapper"
}
}Configuration Options
| Option | Description |
|---|---|
Enabled |
Enables Session API endpoints. |
Domain |
Virtual domain used to access Session API endpoints through a mapped proxy port. |
With the configuration above, Session API can be accessed using requests such as:
curl -x http://127.0.0.1:10201 http://portmapper/session/Using an Empty Domain
The Domain setting is optional and may be set to an empty string:
{
"SessionAPI": {
"Enabled": true,
"Domain": ""
}
}When Domain is empty, Session API endpoints become available directly on the mapped proxy port.
For example:
curl http://127.0.0.1:10201/session/This can be convenient when working with local tools or scripts that do not support custom hostnames.
Get Current Session
Returns information about the session currently assigned to a port.
Example:
curl -x http://127.0.0.1:10201 http://portmapper/session/Response:
{
"session_id": "LZpmRqdu",
"expires_at": "Wed, 10 Jun 2026 16:09:43 GMT",
"expired": false
}If the session is still active, repeated calls return the same information.
When the sticky session expires, ProxyMapService automatically generates a new session ID and the endpoint will return the new session details.
This can be useful for monitoring session state or checking how much time remains before rotation.
Reset Current Session
Sometimes you want to force a session change without waiting for the expiration timer.
The /session/reset endpoint removes the current session associated with the port.
Example:
curl -x http://127.0.0.1:10201 http://portmapper/session/resetResponse:
{
"success": true
}After the reset, the next request through port 10201 will automatically create a new session.
Typical use cases:
- detected or blocked IP address
- captcha escalation
- failed scraping workflow
- manual IP rotation
Create a New Session Immediately
The /session/new endpoint creates a new session immediately and assigns it to the port.
Example:
curl -x http://127.0.0.1:10201 http://portmapper/session/newResponse:
{
"session_id": "uawxmttg",
"expires_at": "Wed, 10 Jun 2026 16:19:48 GMT",
"expired": false
}Unlike /session/reset, which simply removes the current session, /session/new generates and activates a replacement session instantly.
This is useful when an application wants to rotate identities proactively while continuing to use the same local proxy port.
Why Not Just Change Ports?
A common question is why you would need a Session API if every port already has its own sticky session.
In practice, many scraping and automation systems assign a specific role to each local proxy port. For example:
127.0.0.1:10201 → Worker A
127.0.0.1:10202 → Worker B
127.0.0.1:10203 → Worker CWorkers may maintain their own queues, browser profiles, cookies, account assignments, or internal state tied to a particular proxy endpoint.
Changing ports is not always practical because it may require updating application configuration, restarting workers, or reassigning tasks.
With Session API, the application can keep using the same local proxy port while rotating the underlying sticky session whenever necessary.
Practical Examples
Session API can be useful when:
- a target website starts returning captchas
- an IP address becomes blocked or rate-limited
- a scraping task needs a fresh identity immediately
- monitoring systems need visibility into session expiration
- applications want explicit control over session rotation timing
All of this can be done without restarting ProxyMapService and without changing the local proxy endpoint used by the application.
Summary
ProxyMapService was originally designed to make sticky proxies available to software that only understands simple IP:PORT proxy lists.
The new Session API adds direct control over the sticky sessions behind each mapped port.
Available endpoints:
GET /session/— get information about the current sessionGET /session/reset— remove the current sessionGET /session/new— create and activate a new session immediately
This makes it easier to build scraping, automation, and data collection systems that need predictable control over proxy identities while continuing to use ordinary local proxy ports.