List sessions

List visitor sessions for a Clics project with the TypeScript SDK: periods, dimensional filters, domain scoping, and pagination.

Returns a paginated list of visitor sessions for a project, newest first. Use this to browse recent visits, export journeys for a period, or collect sessionId values before calling getSession or listSessionEvents.

This is the SDK equivalent of the Sessions table in the dashboard. It supports date ranges, a domain, and filters for country, device, browser, OS, entry/exit page, and referrer.

Parameters

Date range presets

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

Same presets as queryStats.

Signature

clics.sessions.listSessions(request, options?)

Examples

Last 7 days (default period)

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

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

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

for (const session of result.sessions) {
  console.log(
    session.sessionId,
    session.landingPathname,
    session.durationSeconds,
    session.isBounce ? "bounce" : "engaged",
  );
}

console.log(result.meta.totalRows, "sessions in range");

One production domain

const result = await clics.sessions.listSessions({
  projectId: "proj_xxx",
  domain: "example.com",
  dateRange: "last30days",
  limit: 50,
});

Development traffic only

const result = await clics.sessions.listSessions({
  projectId: "proj_xxx",
  domain: "localhost",
  dateRange: "last7days",
});

Filter by country and device

Pass values as comma-separated strings. Use listSessionFilterValues first when building an interface.

const result = await clics.sessions.listSessions({
  projectId: "proj_xxx",
  dateRange: "last30days",
  country: "US,FR",
  countryOp: "is",
  device: "Mobile",
  deviceOp: "is_not",
});

Custom calendar range

Pass both start and end. dateRange is ignored when they are set.

const result = await clics.sessions.listSessions({
  projectId: "proj_xxx",
  start: "2026-07-01",
  end: "2026-07-15",
  timezone: "Europe/Paris",
  limit: 20,
});

timezone defines the start and end of date-only calendar days and the returned session date. It does not change the original firstHit and lastHit timestamps.

Page through all results

let cursor: string | undefined;
const all = [];

do {
  const page = await clics.sessions.listSessions({
    projectId: "proj_xxx",
    dateRange: "last30days",
    limit: 100,
    cursor,
  });
  all.push(...page.sessions);
  cursor = page.meta.cursor ?? undefined;
} while (cursor);

What it returns

{
  sessions: Array<{
    sessionId: string;
    date: string;              // calendar day of the session
    firstHit: string;          // first hit timestamp
    lastHit: string;           // last hit timestamp
    durationSeconds: number;   // lastHit − firstHit in seconds
    pageviews: number;
    isBounce: boolean;         // true when first and last hit are the same moment
    country: string;
    device: string;            // e.g. Desktop, Mobile, Tablet
    browser: string;
    os: string;
    landingPathname: string;   // first path
    exitPathname: string;      // last path
    referrer: string;          // landing referrer domain, or "direct"
  }>;
  meta: {
    cursor: string | null;     // pass as cursor on the next request; null when done
    isDone: boolean;
    totalRows: number;         // total matching sessions in the range (not just this page)
    timezone: string;
  };
}

Sessions are ordered by firstHit descending (newest first), then sessionId.

Notes

• Requires a paid plan: free tiers get 403
• Passing only start or only end returns 400 (INVALID_DATE_RANGE)
• An invalid cursor returns 400 (INVALID_CURSOR)
• All filters affect meta.totalRows as well as the returned page.

API reference

See List sessions for request and response schemas, status codes, and error types.