Sessions

Inspect active sticky sessions on gateway products. Useful for monitoring long-running scrapes and for cleaning up sessions that shouldn't be using more bandwidth.

ISP doesn't have a sessions API — every ISP IP is itself permanent, so there's no transient session state.

Endpoints

Method	Path	Purpose
GET	/residential/sessions	List active residential sticky sessions
GET	/mobile/sessions	List active mobile sticky sessions
GET	/{product}/sessions/{id}	Details for one session
DELETE	/{product}/sessions/{id}	Terminate a session early

List

curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/sessions?subuser=sub_01HX2K3PQ4M5"

Response:

{
  "data": [
    {
      "id":               "ses_01HX2K3PQ4M5",
      "subuser":          "sub_01HX2K3PQ4M5",
      "session_id":       "job1",
      "region":           "us",
      "state":            "ca",
      "city":             "la",
      "asn":              7922,
      "exit_ip":          "198.51.100.42",
      "started_at":       "2026-05-28T07:00:00Z",
      "expires_at":       "2026-05-28T07:30:00Z",
      "bytes_used":       3145728,
      "requests":         42,
      "repinned":         false
    }
  ],
  "next_cursor": null
}

Filter parameters: subuser, session_id, region, asn, repinned=true|false.

Fields

• session_id is the user-chosen part of the username (e.g. job1 from -session-job1-sesstime-30).
• repinned flips to true if the upstream IP was reassigned mid-session.
• expires_at = started_at + sesstime.

Get one

curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/sessions/ses_01HX2K3PQ4M5"

Same fields as the list plus per-request samples (last 10 requests).

Terminate

curl -X DELETE -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.com/v1/residential/sessions/ses_01HX2K3PQ4M5"

Future requests with that exact username get a new exit IP, as if sesstime had elapsed. The session record is kept for 24h for audit; the entry's status becomes terminated.

Why terminate?

• A worker crashed and you want to ensure no stale state — minor effect since helodata will expire it anyway at expires_at
• You changed your mind about which geo to scrape — easier to drop than wait
• Cleanup as part of incident response

Concurrency note

session_id reuse is allowed; the same session_id under different geo/sub-user counts as a different session. The full username is the session key.

Errors

Status	Code	Meaning
404	session_not_found	Session expired or never existed
403	subuser_scope_mismatch	Token scope doesn't cover this sub-user's product