List session events

Read the pageviews and custom events of one visitor session with the Clics TypeScript SDK.

Use listSessionEvents to see what happened during one visit, in order: pageviews and custom events. Use it after listSessions, once you have a sessionId.

Quick start

1. Find a session

import { Clics } from "@clicsdev/sdk";

const clics = new Clics({ apiKey: process.env.CLICS_API_KEY! });
const projectId = "proj_xxx";

const { sessions } = await clics.sessions.listSessions({
  projectId,
  dateRange: "last7days",
  limit: 1,
});

const session = sessions[0];
if (!session) throw new Error("No sessions found");

If you already have a session ID from a Dashboard session URL, skip this step.

2. Get its timeline

Use the same scope as listSessions. This prevents the session from being excluded by a different period or domain.

const { events, meta } = await clics.sessions.listSessionEvents({
  projectId,
  sessionId: session.sessionId,
  dateRange: "last7days",
  timezone: "Europe/Paris",
});

console.log(meta.timezone); // "Europe/Paris"

timezone sets the calendar boundaries of date ranges and presets. It does not convert or reorder recorded event timestamps.

3. Read the events

Events are already ordered from oldest to newest.

for (const event of events) {
  if (event.action === "pageview") {
    console.log(event.timestamp, "Viewed", event.payload.pathname);
  } else if (event.action === "custom_event") {
    console.log(event.timestamp, "Event", event.payload.event_name);
  } else {
    console.log(event.timestamp, event.action, event.payload);
  }
}

Choose the scope

For a custom range, pass both start and end. It takes precedence over dateRange.

const timeline = await clics.sessions.listSessionEvents({
  projectId,
  sessionId: "sess_xxx",
  domain: "example.com",
  start: "2026-07-01",
  end: "2026-07-15",
  timezone: "Europe/Paris",
});

Available dateRange values: last24h, last7days, last30days, last3months, last12months, monthToDate, quarterToDate, yearToDate, and allTime.

What you receive

type ListSessionEventsResponse = {
  events: Array<{
    timestamp: string;
    action: string;
    payload: Record<string, unknown>;
  }>;
  meta: {
    timezone: string;
  };
};

Payloads are parsed from JSON. If an older payload cannot be parsed, Clics returns { raw: "…" } so its original value is still available.

Empty result and errors

if (events.length === 0) {
  console.log("No events match this session, period, and domain.");
}

An empty events array is valid. First check the domain, period, and timezone. To confirm the session itself exists in the same scope, call getSession.

The full matching timeline is returned in one response. There is no pagination.

Parameters

API reference

See List session events for the REST schema.