Sessions
How OakData groups a visitor's activity into sessions, the 30-minute inactivity window, and what 'live' means.
A session is one continuous visit. Every event carries the session_id it belongs to, so you can reconstruct exactly what a person did from arrival to departure — and the dashboard, REST API, and MCP tools all roll activity up by session.
How sessions are formed
The SDK assigns a session id on the first event and keeps reusing it as long as the visitor stays active. A session ends after 30 minutes of inactivity; the next event after that gap starts a fresh session with a new id and an incremented session_number (1 for their first-ever session, 2 for the next, and so on).
Sessions span page loads
The session id is sticky across reloads and navigations within the 30-minute window — it's stored client-side, not tied to a single page. Closing the tab and returning 10 minutes later continues the same session; returning the next day starts a new one.
Session end
When the SDK boots and finds that the previous session had already timed out, it emits a $session_end event to close it out cleanly. This is automatic — you never call it.
Reading session ids
Get the current session id at any time. It's useful for correlating a server-side log line with a front-end session, or for deep-linking to a replay.
import oak from 'oakdata-js'
const sessionId = oak.getSessionId() // e.g. "s_a1b2c3" (null before init)"Live" sessions
The live view (and the /api/v1/live endpoint / live_now MCP tool) counts sessions with activity in the last 5 minutes— a tighter window than the 30-minute session timeout, so "live" reflects who is genuinely on the site right now rather than everyone whose session hasn't expired.
Inspecting a session
Use GET /api/v1/sessions to list recent sessions, then /api/v1/sessions/{id} for the full ordered event timeline of a single one. An agent can do the same with list_sessions and get_session over MCP.