Get session

Get details for a visitor session with the TypeScript SDK: UTM metadata, bounce, duration, and visited pages.

Returns one visitor session with everything you need for a detail view: timing, bounce, device and geo metadata, UTM campaign fields, landing/exit paths, and the list of pages visited (with counts).

Get the sessionId from listSessions or from the dashboard Sessions detail URL. For the chronological activity stream (pageviews + custom events), use listSessionEvents.

Parameters

Why date range on a get-by-id?

The underlying analytics store can scope by time. Defaulting to allTime makes lookup by ID reliable when you do not know when the visit happened. If you already know the window (for example you just listed last7days), you can pass the same dateRange for consistency.

Date range presets

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

Signature

clics.sessions.getSession(request, options?)

Examples

By session ID

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

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

const session = await clics.sessions.getSession({
  projectId: "proj_xxx",
  sessionId: "sess_xxx",
});

console.log({
  referrer: session.referrer,
  durationSeconds: session.durationSeconds,
  isBounce: session.isBounce,
  utmSource: session.utmSource,
  pages: session.pages,
});

After listing recent sessions

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

const first = sessions[0];
if (!first) {
  throw new Error("No sessions in range");
}

const detail = await clics.sessions.getSession({
  projectId: "proj_xxx",
  sessionId: first.sessionId,
  dateRange: "last7days",
});

for (const page of detail.pages) {
  console.log(page.pathname, page.pageVisits);
}

Scoped to a domain

const session = await clics.sessions.getSession({
  projectId: "proj_xxx",
  sessionId: "sess_xxx",
  domain: "example.com",
});

Custom calendar range in a timezone

Use an IANA timezone when a date-only range must follow the site or report’s local calendar. It defines calendar boundaries and the returned date; the original hit timestamps are unchanged.

const session = await clics.sessions.getSession({
  projectId: "proj_xxx",
  sessionId: "sess_xxx",
  start: "2026-07-01",
  end: "2026-07-15",
  timezone: "Europe/Paris",
});

What it returns

{
  sessionId: string;
  date: string;
  firstHit: string;
  lastHit: string;
  durationSeconds: number;
  pageviews: number;
  isBounce: boolean;
  country: string;
  device: string;
  browser: string;
  os: string;
  landingPathname: string;
  exitPathname: string;
  referrer: string;          // domain, or "direct"
  utmSource: string;
  utmMedium: string;
  utmCampaign: string;
  utmTerm: string;
  utmContent: string;
  totalPageVisits: number;   // sum of page visit counts (at least 1)
  pages: Array<{
    pathname: string;
    pageVisits: number;
  }>;
  meta: {
    timezone: string;
  };
}

pages lists distinct pathnames for the visit (ordered by visits descending, then path). Empty pathnames are omitted. UTM fields are empty strings when not present on the landing hit. meta.timezone is the IANA timezone used for the returned calendar date and the selected range.

Errors

Notes

• Prefer listSessionEvents for the timeline (ordered hits and custom events). pages is a summary by path, not a chronological journey
• Bounce and duration match dashboard Sessions definitions

API reference

See Get session for request and response schemas, status codes, and error types.