A session is one continuous visit. Every event carries its session_id, 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 reuses it while the visitor stays active. A session ends after 30 minutes of inactivity; the next event starts a fresh session with a new id and an incremented session_number (1 for the first-ever session, 2 for the next, and so on).
Sessions span page loads
The session id is stored client-side, not tied to a single page, so it survives reloads and navigations within the 30-minute window. 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 the previous session already timed out, it emits a $session_end event to close it cleanly. This is automatic - you never call it.
Reading session ids
Get the current session id at any time - useful for correlating a server log line with a front-end session, or 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 (the /api/v1/live endpoint and the live_now MCP tool) counts sessions with activity in the last 5 minutes- much tighter than the 30-minute timeout, so "live" means genuinely on the site right now.
Inspecting a session
Use GET /api/v1/sessions to list recent sessions, then /api/v1/sessions/{id} for the full event timeline of one. An agent can do the same with list_sessions and get_session over MCP.