v1

latestSwagger 2.02026-07-1745100168.1 KB

sessions

Get a play session by ID

get/sessions/{id}

Path parameters

idstring required

Session ID

Response

bytesinteger

Bytes is the cumulative bytes sent to this client since session open. HLS/DASH: sum of segment + manifest response bodies. RTMP/SRT: write bytes from the publisher's outbound pipeline.

close_reason'idle' | 'max_lifetime' | 'client_gone' | 'shutdown' | 'kicked'

closed_atstring

ClosedAt is set when the session ends. nil while active.

countrystring

Country is an ISO 3166-1 alpha-2 country code from the configured GeoIP resolver, or "" when GeoIP is disabled / lookup failed.

dvrboolean

DVR is true when the playlist request carried any timeshift query parameter (from / delay / dur / ago) — false for live-edge hits. Set by sessions.HTTPMiddleware after detecting the query shape. The flag also participates in the session fingerprint, so a viewer watching both live and timeshift gets two distinct session records.

idstring

ID uniquely identifies the session across the server's lifetime. For segment protocols (HLS/DASH) it is the deterministic fingerprint hash (so reconnects within the idle window collapse onto one session); for connection-bound protocols (RTMP/SRT/RTSP) it is a random UUID.

ipstring

IP is the remote peer address (no port). For HTTP-based protocols this is the X-Forwarded-For head when present, otherwise the RemoteAddr.

named_by'token' | 'config' | 'fingerprint'

opened_atstring

OpenedAt is the time the first activity for this session was observed.

query_stringstring

QueryString is the raw query of the FIRST request that opened the session (HLS/DASH) — useful when token/abr-variant info is encoded there.

refererstring

Referer is the HTTP Referer when present (HLS/DASH only).

secureboolean

Secure is true when the underlying transport was TLS / SRTS / RTMPS.

started_atstring

StartedAt is when the first byte of media was delivered (segment data for HLS/DASH, first frame after RTMP play handshake). Zero before media flows.

stream_codestring

StreamCode is the foreign key to Stream.Code.

tokenstring

Token is the value of ?token= from the first request, when present. When set, NamedBy is SessionNamedByToken.

updated_atstring

UpdatedAt is the time of the most recent activity. Idle reaper closes sessions whose UpdatedAt is older than (now - idle_timeout).

user_agentstring

UserAgent is the browser/player User-Agent (HTTP) or the equivalent flashVer field for RTMP. May be empty.

user_namestring

UserName is a human label. Resolved from token claims if available, otherwise the fingerprint hash short form. Empty when no identity could be resolved.