Skip to main content

​
Overview

Session analytics help you understand how users interact with your website during individual visits. Track session duration, bounce rates, and session flow.

​
Query Types

​
Session Metrics

Get aggregate session statistics including duration and bounce rate. Query Type: session_metrics 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["session_metrics"],
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }'
Response Fields:
​
total_sessions
number
Total number of sessions in the period.
​
avg_session_duration
number
Average session duration in seconds.
​
bounce_rate
number
Percentage of single-page sessions (0-100).
​
total_events
number
Total events across all sessions.

​
Session Duration Distribution

Analyze how session durations are distributed across time ranges. Query Type: session_duration_distribution 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["session_duration_distribution"],
    "preset": "last_30d"
  }'
Response Fields:
​
duration_range
string
Duration bucket: 0-30s, 30s-1m, 1m-5m, 5m-15m, 15m-1h, or 1h+.
​
sessions
number
Number of sessions in this duration range.
​
visitors
number
Unique visitors with sessions in this range.

​
Sessions by Device

Breakdown of sessions by device type. Query Type: sessions_by_device 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["sessions_by_device"],
    "preset": "last_7d"
  }'
Response Fields:
​
name
string
Device type: desktop, mobile, or tablet.
​
sessions
number
Number of sessions from this device type.
​
visitors
number
Unique visitors using this device.
​
avg_session_duration
number
Average session duration in seconds for this device.

​
Sessions by Browser

Breakdown of sessions by browser. Query Type: sessions_by_browser 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["sessions_by_browser"],
    "preset": "last_30d",
    "limit": 20
  }'
Response Fields:
​
name
string
Browser name (e.g., Chrome, Safari, Firefox).
​
sessions
number
Number of sessions from this browser.
​
visitors
number
Unique visitors using this browser.
​
avg_session_duration
number
Average session duration in seconds for this browser.

​
Sessions Time Series

Track session metrics over time to identify trends. Query Type: sessions_time_series 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": [
      {
        "name": "sessions_time_series",
        "granularity": "daily"
      }
    ],
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }'
Response Fields:
​
date
string
Date of the data point (YYYY-MM-DD).
​
sessions
number
Number of sessions on this date.
​
visitors
number
Unique visitors on this date.
​
avg_session_duration
number
Average session duration in seconds.

​
Session Flow

Analyze which pages are most commonly visited during sessions. Query Type: session_flow 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["session_flow"],
    "preset": "last_7d",
    "limit": 50
  }'
Response Fields:
​
name
string
Page path.
​
sessions
number
Number of sessions that included this page.
​
visitors
number
Unique visitors who viewed this page.

​
Session List

Retrieve detailed information about individual sessions including all events. Query Type: session_list 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["session_list"],
    "preset": "today",
    "limit": 25,
    "page": 1
  }'
Response Fields:
​
session_id
string
Unique session identifier.
​
first_visit
string
Timestamp of first event in session.
​
last_visit
string
Timestamp of last event in session.
​
page_views
number
Number of page views in this session.
​
visitor_id
string
Anonymous visitor identifier.
​
country
string
Visitor’s country code.
​
referrer
string
Session referrer URL.
​
device_type
string
Device type used in session.
​
browser_name
string
Browser name.
​
os_name
string
Operating system name.
​
events
array
Array of all events in the session, including custom events. Each event contains:
  • id: Event ID
  • time: Event timestamp
  • event_name: Event name
  • path: Page path
  • properties: Event properties (if any)
Example Response: 
{
  "success": true,
  "data": [
    {
      "parameter": "session_list",
      "success": true,
      "data": [
        {
          "session_id": "sess_abc123",
          "first_visit": "2024-01-15T10:30:00Z",
          "last_visit": "2024-01-15T10:45:00Z",
          "page_views": 5,
          "visitor_id": "vis_xyz789",
          "country": "US",
          "referrer": "https://google.com",
          "device_type": "desktop",
          "browser_name": "Chrome",
          "os_name": "Windows",
          "events": [
            ["evt_1", "2024-01-15T10:30:00Z", "screen_view", "/home", null],
            ["evt_2", "2024-01-15T10:32:15Z", "screen_view", "/products", null],
            ["evt_3", "2024-01-15T10:35:30Z", "button_click", "/products", "{\"button_id\":\"add_to_cart\"}"],
            ["evt_4", "2024-01-15T10:40:00Z", "screen_view", "/cart", null],
            ["evt_5", "2024-01-15T10:45:00Z", "page_exit", "/cart", null]
          ]
        }
      ]
    }
  ]
}

​
Session Definition

A session in Databuddy is defined as:
  • A sequence of events from the same visitor
  • Sessions timeout after 30 minutes of inactivity
  • A new session starts when:
    • The visitor returns after 30+ minutes
    • UTM parameters change
    • The referrer changes (external traffic)

​
Bounce Rate Calculation

Bounce rate represents non-engaged sessions. A session is considered a bounce if:
  • Only one pageview occurs, AND
  • Session duration is less than 10 seconds, AND
  • No custom events or interactions occur
This definition focuses on meaningful engagement rather than raw single-page visits.

​
Filter Example

Get mobile sessions from organic traffic: 
curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": ["session_metrics", "sessions_by_browser"],
    "preset": "last_30d",
    "filters": [
      {
        "field": "device_type",
        "op": "eq",
        "value": "mobile"
      },
      {
        "field": "utm_medium",
        "op": "eq",
        "value": "organic"
      }
    ]
  }'

​
Notes

  • Session data includes both pageview events and custom events
  • The session_list query merges data from both the events table and custom_events table
  • Session attribution automatically applies UTM parameters from the first pageview to all session events
  • Duration is calculated from actual time spent on pages (excluding page_exit events)
  • Very short sessions (under 1 second) and very long outliers (over 1 hour) are filtered from averages