Sessions

List visitor sessions, fetch session details, and read session event timelines with the Clics TypeScript SDK.

A session is one visitor visit on your site, from the first hit to the last. It includes landing and exit pages, duration, whether the visit bounced, referrer and device metadata, UTM fields, and a chronological event timeline.

Use Sessions when aggregate Stats are not enough, you need to inspect individual journeys, debug a conversion path, export recent visits, or reconstruct what a visitor did page by page.

Sessions vs Stats

	Stats (`queryStats`)	Sessions (`clics.sessions`)
Grain	Aggregates (totals, rates, breakdowns)	One row per visit
Typical question	“How many visitors last week?”	“What did this visit look like?”
Bounce / duration	Rates and averages	Per-session `isBounce` and `durationSeconds`
Timeline	No	Yes: pages + events

Start with Stats for dashboards and KPIs. Switch to Sessions when you need the visit-level detail behind those numbers.

What each method returns

Method	Use it to…	Main payload
`listSessions`	Browse or export visits for a period	Paginated `sessions[]` + `meta`
`listSessionFilterValues`	Populate a filter picker from real traffic	Values with session/pageview counts
`getSession`	Inspect one visit (UTM, pages visited)	Session detail + `pages[]`
`listSessionEvents`	Rebuild the activity timeline	Chronological `events[]`

Core concepts

Concept	Meaning in the API
Duration	Seconds between the first and last hit (`durationSeconds`)
Bounce	`isBounce: true` when first and last hit are the same moment, typically a single pageview and `0` duration
Referrer	Landing referrer domain; empty referrers appear as `"direct"`
Landing / exit	First and last pathnames in the session
Pages (detail only)	Distinct paths visited, with visit counts
Events	Ordered pageviews and custom events for that session

These definitions match the dashboard Sessions view and the bounce / visit-duration KPIs on Overview.

Date ranges and domain

Period presets (same vocabulary as queryStats):

last24h · last7days · last30days · last3months · last12months · monthToDate · quarterToDate · yearToDate · allTime

Method	Default when unset
`listSessions`	`last7days`
`getSession` / `listSessionEvents`	`allTime` (so you can look up a session by ID without knowing the window)

For a custom window, pass both start and end (yyyy-MM-dd or ISO8601). When both are set, dateRange is ignored.

Domain:

Omit domain → all production hostnames for the project (localhost excluded)
domain: "example.com" → that hostname only
domain: "localhost" → development traffic only (project must allow localhost)

Pagination

listSessions uses cursor pagination (like projects and funnels):

Request: optional cursor, limit (1–100, default 20)
Response meta: cursor (next page or null), isDone, totalRows

Pass meta.cursor on the next call until isDone is true.

Typical workflow

Optionally call listSessionFilterValues to discover valid filter values for the selected scope
Call listSessions for the period, domain, and optional dimensional filters you care about
Pick a sessionId from the list (newest first)
Call getSession for UTM metadata and visited pages
Call listSessionEvents for the full activity timeline

Session filters

listSessions supports comma-separated values for country, device, browser, os, pageEntry, pageExit, and referrer. Use the matching ...Op (is or is_not) when you need exclusion. List filter values lets you populate a UI without hard-coding those values.

Methods

Access session methods via clics.sessions.

Sessions in the dashboard: UI explorer with richer filters
Stats: aggregate KPIs and breakdowns
Custom Events: how track() events appear in session timelines
CLI: clics sessions list|get|events
MCP: list_sessions, get_session, list_session_events

Inspect visitor sessions with the Clics TypeScript SDK

Sessions