List sessions

Sessions that started in the date range, newest first, including ones still in progress: the list on the Sessions page. A session is one visit, and it closes after 30 minutes without activity.

duration and isBounce are settled when a session ends. The tracking script ends a session whenever its tab is hidden or closed, and a later page view reopens it, so until its first end a session shows duration 0 and isBounce false.

Keys: an account key. Getting started explains both kinds.

Parameters

Prop	In	Type	Notes
`contactListId`	`query`	`string`	The id of the audience (the tracked site) to read, a UUID: anything else returns a 400. You must be a member of the workspace the audience belongs to, or the call returns a 401. An id that matches no audience is not an error: the call returns no data.
`startDate`	`query`	`string`	Start of the date range, read as UTC: a date such as `2026-09-01` (from midnight), or an exact time such as `2026-09-01T09:30:00Z`. Use one of these two forms.
`endDate`	`query`	`string`	End of the date range, read as UTC. A date such as `2026-09-30` includes that whole day; an exact time such as `2026-09-30T18:00:00Z` ends the range right before that moment. If the workspace has gone past its plan's event allowance this billing period, the range is cut short at the moment the allowance ran out.
`page`	`query`	`number`	Page number, starting at 0.
`pageSize`	`query`	`number`	Rows per page.
`search?`	`query`	`string`	Keep only sessions whose entry path, entry hostname, visitor email or visitor id contains this text, ignoring case.
`filter?`	`query`	`string`	Narrows the results: a URL-encoded JSON array of conditions, each `[key, values, operator]`, where a missing operator means `is`. Example: `[["country",["US","GB"]],["page",["/pricing"],"startsWith"]]` keeps visits from the US or the UK that viewed a page starting with `/pricing`. Every condition must match, and each key can appear once (a second condition on the same key replaces the first). A condition matches any of its values, except that `isNot`, `notContains` and `notRegex` rule out all of them. Operators: `is` and `isNot` (exact), `contains`, `notContains`, `startsWith` and `endsWith` (ignoring case), `regex` and `notRegex` (RE2 syntax, so no lookarounds; a pattern that does not compile returns a 400), and `isNull` and `isNotNull` (the value is not set, or is set; send `[]` as the values). Keys: `channel`, `referrer_source`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `country` (a two-letter code), `region`, `city`, `browser`, `browser_version`, `os`, `os_version`, `screen_size` (`Desktop`, `Mobile` or `Tablet`), `hostname`, `entry_page`, `exit_page`, `page` and `event_name` (visits that viewed such a page or sent such an event), `identified` (`["true"]` or `["false"]`), `goal_id` (people who completed the goal in the range) and `cohort_id` (members of a segment). The last two take ids and only `is` or `isNot`. Unknown keys, and a `filter` that is not valid JSON, are ignored rather than refused.

Response

Prop	Type	Notes
`content`	`SessionListRow[]`	One row per session, newest first.
`size`	`number`	The `pageSize` you asked for.
`page`	`number`	The page you asked for, counted from 0.
`totalItems`	`number`	Rows across all pages.
`totalPages`	`number`	`totalItems` divided by `size`, rounded up.

Each item in `content`

Prop	Type	Notes
`id`	`string`	The session id.
`visitorId`	`string`	The visitor (browser) the session belongs to.
`visitorDisplay`	`string`	The visitor's email when identified, else the visitor id.
`contactId`	`string`	The person id when the visitor is identified. Left out for anonymous visitors.
`startedAt`	`string`	When the session started, in UTC with milliseconds, such as `2026-09-30 14:03:12.345+00`.
`duration`	`number`	Length in milliseconds as last reported, 0 until the session first ends.
`pageCount`	`number`	Page views in the session.
`entryPath`	`string`	Path of the first page.
`entryHostname`	`string`	Hostname of the first page.
`isBounce`	`boolean`	true when the session had one page and no interactions (your own events or link clicks; the automatic scroll event does not count). It is set when the session ends, so it reads false until then.
`exitPath`	`string`	Path of the last page viewed so far.
`exitHostname`	`string`	Hostname of that last page.
`eventCount`	`number`	Everything recorded in the session: page views, your own events, scroll and link-click events.
`channel`	`string`	Channel the visit came through, such as `Organic Search` or `Direct`.
`referrerSource`	`string`	Source of the visit, such as `Google`, '' when none.
`country`	`string`	Two-letter country code, '' when unknown.
`region`	`string`	Region, '' when unknown.
`city`	`string`	City, '' when unknown.
`browser`	`string`	Browser, such as `Chrome`.
`os`	`string`	Operating system, such as `Windows`.
`device`	`string`	`Desktop`, `Mobile` or `Tablet`.

Request

curl 'https://app.spreelytics.com/api/v1/event/analytics/web-analytics/sessions?contactListId=…&startDate=…&endDate=…&page=…&pageSize=…' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const url = new URL('https://app.spreelytics.com/api/v1/event/analytics/web-analytics/sessions');
url.searchParams.set('contactListId', '…');
url.searchParams.set('startDate', '…');
url.searchParams.set('endDate', '…');
url.searchParams.set('page', '…');
url.searchParams.set('pageSize', '…');

const res = await fetch(url, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const data = await res.json();

import requests

res = requests.get(
    "https://app.spreelytics.com/api/v1/event/analytics/web-analytics/sessions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"contactListId": "…", "startDate": "…", "endDate": "…", "page": "…", "pageSize": "…"},
)
data = res.json()

Response

{
  "content": [
    {
      "id": "string",
      "visitorId": "string",
      "visitorDisplay": "string",
      "contactId": "string",
      "startedAt": "string",
      "duration": 0,
      "pageCount": 0,
      "entryPath": "string",
      "entryHostname": "string",
      "isBounce": true,
      "exitPath": "string",
      "exitHostname": "string",
      "eventCount": 0,
      "channel": "string",
      "referrerSource": "string",
      "country": "string",
      "region": "string",
      "city": "string",
      "browser": "string",
      "os": "string",
      "device": "string"
    }
  ],
  "size": 0,
  "page": 0,
  "totalItems": 0,
  "totalPages": 0
}

PreviousList event property keys Next Get a session

List sessions

Parameters

Response

Each item in `content`

See your own numbers today.

Tell us what you need.

List sessions

Parameters

Response

Each item in content

See your own numbers today.

Each item in `content`