Site Analytics APIs

Site Analytics

Site-scoped events, metrics, timeseries, and aggregated dashboard views.

Audience: Teams building site-level analytics dashboards and diagnostics.

Critical: All endpoints are under /api/v1/analytics/sites/:siteId and require analytics permission.

Overview Event Sequences Identity Conversion

Who This Page Is For

Use this page when you need direct site-level event streams and aggregate metrics for custom analytics pages or internal dashboards.

Quick Start (2-5 Minutes)

Fetch site metrics

Load unified KPI metrics for selected lookback.

GET /api/v1/analytics/sites/:siteId/metrics?days=30

Fetch site events

Get paged event feed with optional event/entity filters.

GET /api/v1/analytics/sites/:siteId/events?limit=100&offset=0&eventType=product_view

Fetch event type counts

Get type-level distribution for quick diagnostics.

GET /api/v1/analytics/sites/:siteId/events/types?days=30

Fetch timeseries

Render timeline charts for event flows.

GET /api/v1/analytics/sites/:siteId/events/timeseries?range=30d&eventType=purchase

Fetch advanced dashboard aggregate

Use root site analytics endpoint for composite dashboard payload.

GET /api/v1/analytics/sites/:siteId?timeRange=7d

Site analytics endpoints

GET /api/v1/analytics/sites/:siteId/datalayer/events
GET /api/v1/analytics/sites/:siteId/events/types
GET /api/v1/analytics/sites/:siteId/events
GET /api/v1/analytics/sites/:siteId/metrics
GET /api/v1/analytics/sites/:siteId/events/timeseries
GET /api/v1/analytics/sites/:siteId

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	All site analytics endpoints	Site boundary for all analytics output.
`days or timeRange`	Optional	`number or 24h\|7d\|30d`	metrics and root aggregate endpoint	Time window selector for aggregate output.
`limit / offset`	Optional	`number`	events and datalayer/events	Pagination controls.
`eventType / entityType`	Optional	`string`	events and timeseries	Filter controls for focused analysis.
`range`	Optional	`string`	events/timeseries	Preset range for timeline aggregation.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need raw-ish event feed	/analytics/sites/:siteId/events	Paged event stream for investigation.
Need KPI cards	/analytics/sites/:siteId/metrics	Unified metric payload for summary UI.
Need timeline charts	/analytics/sites/:siteId/events/timeseries	Time bucketed trend data.
Need event taxonomy snapshot	/analytics/sites/:siteId/events/types	Event type volume distribution.
Need single composite payload	/analytics/sites/:siteId	Aggregated dashboard response for advanced page.

Common Errors and Fixes

Events endpoint latency spikes

Cause: Large limit with broad no-filter queries.

Fix: Use reasonable limit and scoped filters.

Timeseries chart seems flat

Cause: Event filter too narrow or low-volume event type.

Fix: Remove eventType filter and re-check baseline.

Root aggregate endpoint not matching cards

Cause: Different days/timeRange parameters used across calls.

Fix: Align parameters for consistent outputs.

Datalayer events unexpectedly empty

Cause: Data layer integration disabled or not emitting events.

Fix: Verify data-layer integration config and runtime event pushes.

Production Checklist

Site dashboards define consistent default range values.Required
Events queries are paginated and filtered to prevent heavy payloads.Required
Timeseries and KPI cards use aligned windows.Required
Datalayer event monitoring is included in integration QA.Required
Site access permissions are validated for all analytics consumers.Required