# Visits & sessions

> How OakData groups a visitor's activity into sessions, the 30-minute inactivity window, and what 'live' means.

Source: https://oakdata.co/docs/concepts/sessions

---

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.

Two sessions of events separated by a 30-minute inactivity gap.

A gap of 30+ minutes ends a session; the next event starts a new one, numbered in order.

## 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](https://oakdata.co/docs/concepts/replay-privacy).

**session**

```ts
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](https://oakdata.co/docs/api/rest) 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](https://oakdata.co/docs/api/mcp).