Analytics API

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

All analytics endpoints require authentication and return cached data when available for optimal performance.

Overview Stats

Get high-level metrics for your workspace.

GET /api/v1/analytics/overview

Parameters

Param	Type	Default	Description
`start`	ISO date	30 days ago	Start of date range
`end`	ISO date	now	End of date range

Response

{
  "pageviews": 45000,
  "uniqueVisitors": 12500,
  "sessions": 18000,
  "avgDuration": 185,
  "bounceRate": 42.5,
  "topPages": [...],
  "comparison": {
    "pageviews": { "current": 45000, "previous": 42000, "change": 7.14 }
  },
  "fromCache": true,
  "period": { "start": "2025-01-01T00:00:00Z", "end": "2025-01-05T23:59:59Z" }
}

Visitors Time Series

GET /api/v1/analytics/visitors

Parameters

Param	Type	Default	Description
`start`	ISO date	30 days ago	Start of date range
`end`	ISO date	now	End of date range
`granularity`	string	`day`	`hour`, `day`, or `week`

Response

{
  "data": [
    { "date": "2025-01-01", "visitors": 450, "sessions": 520 },
    { "date": "2025-01-02", "visitors": 480, "sessions": 550 }
  ],
  "granularity": "day",
  "fromCache": true
}

Top Pages

GET /api/v1/analytics/pages

Parameters

Param	Type	Default	Description
`start`	ISO date	30 days ago	Start of date range
`end`	ISO date	now	End of date range
`limit`	number	20	Max results

Response

{
  "data": [
    { "path": "/", "title": "Home", "pageviews": 12000, "visitors": 8000, "avgTime": 45 },
    { "path": "/pricing", "title": "Pricing", "pageviews": 5500, "visitors": 4200, "avgTime": 120 }
  ],
  "fromCache": true
}

Traffic Sources

GET /api/v1/analytics/sources

Response

{
  "referrers": [
    { "source": "google.com", "visitors": 5000, "sessions": 6200 },
    { "source": "twitter.com", "visitors": 1200, "sessions": 1400 }
  ],
  "utmSources": [
    { "source": "newsletter", "medium": "email", "visitors": 800 }
  ],
  "fromCache": true
}

Events Breakdown

GET /api/v1/analytics/events

Parameters

Param	Type	Default	Description
`start`	ISO date	30 days ago	Start of date range
`end`	ISO date	now	End of date range

Response

{
  "data": [
    { "type": "$pageview", "count": 45000, "users": 12500, "auto": true },
    { "type": "signup_clicked", "count": 850, "users": 780, "auto": false }
  ],
  "fromCache": true
}

Campaigns (UTM)

GET /api/v1/analytics/campaigns

Response

{
  "campaigns": [
    { "name": "summer_sale", "source": "google", "medium": "cpc", "visitors": 2500, "sessions": 3200 }
  ],
  "adPlatforms": [
    { "platform": "Google Ads", "visitors": 3500 },
    { "platform": "Facebook Ads", "visitors": 1200 }
  ],
  "fromCache": true
}

Channels

GET /api/v1/analytics/channels

Attribution breakdown by marketing channel.

Response

{
  "data": [
    { "channel": "Organic Search", "visitors": 8000, "sessions": 9500, "percentage": 45.2 },
    { "channel": "Direct", "visitors": 4500, "sessions": 5000, "percentage": 25.4 },
    { "channel": "Paid Search", "visitors": 2500, "sessions": 3000, "percentage": 14.1 }
  ],
  "fromCache": true
}

Devices

GET /api/v1/analytics/devices

Response

{
  "browsers": [
    { "browser": "Chrome", "count": 25000 },
    { "browser": "Safari", "count": 12000 }
  ],
  "devices": [
    { "device": "Desktop", "count": 30000 },
    { "device": "Mobile", "count": 15000 }
  ],
  "operatingSystems": [
    { "os": "Windows", "count": 18000 },
    { "os": "macOS", "count": 12000 }
  ],
  "fromCache": true
}

Geography

GET /api/v1/analytics/geo

Response

{
  "countries": [
    { "country": "US", "visitors": 15000 },
    { "country": "DE", "visitors": 8000 },
    { "country": "CH", "visitors": 5000 }
  ],
  "cities": [
    { "city": "New York", "country": "US", "visitors": 2500 },
    { "city": "Zurich", "country": "CH", "visitors": 1800 }
  ],
  "fromCache": true
}

UX Insights

GET /api/v1/analytics/ux-insights

Dead clicks, rage clicks, and scroll depth analysis.

Parameters

Param	Type	Default	Description
`days`	number	30	Lookback period in days

Response

{
  "totals": {
    "dead_clicks": 245,
    "rage_clicks": 89,
    "dead_click_rate": 2.4,
    "rage_click_rate": 0.9,
    "total_sessions": 10000
  },
  "dead_clicks_by_page": [
    { "doc_path": "/checkout", "dead_clicks": 45, "affected_sessions": 38 }
  ],
  "rage_clicks_by_page": [...],
  "low_scroll_pages": [
    { "doc_path": "/pricing", "avg_scroll_depth": 35, "samples": 250 }
  ],
  "fromCache": true
}

Realtime

GET /api/v1/analytics/realtime

Get current active visitors (cached for 60 seconds).

Response

{
  "activeVisitors": 42,
  "activePages": [
    { "path": "/", "visitors": 15 },
    { "path": "/pricing", "visitors": 8 }
  ],
  "countries": ["US", "DE", "CH"],
  "devices": { "desktop": 28, "mobile": 14 },
  "fromCache": true
}