Skip to main content
The Sessions API provides endpoints to query and analyze user sessions.

​
List sessions

GET /api/websites/:id/sessions Retrieve a paginated list of sessions for a website.

​
Path parameters

​
id
string
required
Website ID (format: site_XXXXXXXXXX)

​
Query parameters

​
start_date
string
Start date (YYYY-MM-DD). Defaults to 7 days ago.
​
end_date
string
End date (YYYY-MM-DD). Defaults to today.
​
timezone
string
Timezone for date range. Defaults to UTC.
​
cursor
string
Pagination cursor from previous response
​
limit
number
Number of sessions to return (max 100). Defaults to 50.
​
include_bots
boolean
Include bot sessions. Defaults to false.
All standard filters are supported: filter_country, filter_page, filter_referrer, filter_browser, filter_os, filter_device, filter_language, filter_utm_source, filter_utm_medium, filter_utm_campaign, filter_region, filter_city, filter_hostname.

​
Response

​
sessions
array
Array of session objects
​
next_cursor
string
Cursor for next page of results (null if no more results)

​
Example

curl -X GET "https://analytics.example.com/api/websites/site_abc123/sessions?limit=10" \
  -H "Authorization: Bearer spk_selfhosted_abc123..."
Response
{
  "sessions": [
    {
      "session_id": "sess_xyz789",
      "visitor_id": "a1b2c3d4e5f6g7h8",
      "started_at": "2026-03-03T10:15:00Z",
      "ended_at": "2026-03-03T10:45:00Z",
      "duration": 1800,
      "pageviews": 5,
      "events": 2,
      "is_bounce": false,
      "country": "US",
      "browser": "Chrome",
      "os": "macOS",
      "device": "desktop"
    }
  ],
  "next_cursor": "eyJpZCI6MTIzNDU2fQ=="
}

​
Get session details

GET /api/websites/:id/sessions/:session_id Retrieve detailed information about a specific session, including all events.

​
Path parameters

​
id
string
required
Website ID
​
session_id
string
required
Session ID

​
Response

​
session
object
Session metadata (same fields as list endpoint)
​
events
array
Array of all events in the session

​
Example

curl -X GET "https://analytics.example.com/api/websites/site_abc123/sessions/sess_xyz789" \
  -H "Authorization: Bearer spk_selfhosted_abc123..."
Response
{
  "session": {
    "session_id": "sess_xyz789",
    "visitor_id": "a1b2c3d4e5f6g7h8",
    "started_at": "2026-03-03T10:15:00Z",
    "ended_at": "2026-03-03T10:45:00Z",
    "duration": 1800,
    "pageviews": 5,
    "events": 2,
    "is_bounce": false,
    "country": "US",
    "browser": "Chrome",
    "os": "macOS",
    "device": "desktop"
  },
  "events": [
    {
      "event_type": "pageview",
      "timestamp": "2026-03-03T10:15:00Z",
      "url": "/",
      "referrer": "https://google.com"
    },
    {
      "event_type": "pageview",
      "timestamp": "2026-03-03T10:16:30Z",
      "url": "/pricing"
    },
    {
      "event_type": "event",
      "timestamp": "2026-03-03T10:17:00Z",
      "event_name": "signup_click",
      "event_data": {"plan": "pro"}
    }
  ]
}

​
Session timeout

Sessions expire after 30 minutes of inactivity. A new pageview or event after 30 minutes starts a new session.
Session IDs are generated server-side. No cookies or client-side session storage is used.

​
Use cases

Session Replay

Build session replay features by reconstructing user journeys

Funnel Analysis

Analyze session paths through your application

Engagement Metrics

Calculate average session duration and pages per session

Behavior Patterns

Identify common user behavior patterns and session flows

Build docs developers (and LLMs) love

Get started for freeTalk to us