Analytics Overview

Entry point for organization-level KPI monitoring and activity diagnostics.

Audience: Product, growth, and data teams monitoring cross-module performance.

Critical: All overview endpoints are authenticated and permission-protected (analytics:view).

Product Analytics Category Analytics Analytics Migration v2 Cohorts Funnels Journeys Revenue Analytics

Who This Page Is For

Use this page when you need top-level metrics, dashboard summary snapshots, and recent activity context before drilling into module-specific analytics.

Breaking change note: Cohort analytics now uses a single V2 report endpoint (GET /api/v1/analytics/cohort/:siteId). Legacy comparison and churn cohort endpoints were removed.

Breaking change note (Product + Category analytics v2): product drilldowns are now productId (UUID) based and legacy product routes were removed on February 16, 2026.

Breaking Endpoint Map (Product + Category Analytics v2)

Removed	Replacement	Required Contract Change
GET /api/v1/analytics/product/sites/:siteId/top-revenue	GET /api/v1/analytics/product/:siteId/top	Use v2 top response with required currency field.
GET /api/v1/analytics/product/:siteId/bought-together	GET /api/v1/analytics/product/:siteId/associations?source=purchase	Send productId (UUID), not productItemCode.
GET /api/v1/analytics/product/:siteId/added-to-cart-together	GET /api/v1/analytics/product/:siteId/associations?source=cart	Mode filter moved to mode=all\|session\|cart.
GET /api/v1/sites/:siteId/products (analytics picker usage)	GET /api/v1/analytics/product/:siteId/catalog	Analytics product picker is now ANALYTICS_VIEW scoped.

Quick Start (2-5 Minutes)

Fetch organization overview

Retrieve high-level metrics for configured time window.

GET /api/v1/analytics/overview?days=30&siteId=SITE_ID

Fetch recent activity logs

Inspect recent event-level activity by site and limit.

GET /api/v1/analytics/activity-logs?siteId=SITE_ID&limit=50

Load dashboard summary

Get consolidated KPI set for dashboard cards/widgets.

GET /api/v1/analytics/dashboard-summary?days=30&siteId=SITE_ID

Inspect event breakdown

Fetch event-type aggregation for traffic diagnostics.

GET /api/v1/analytics/events/breakdown?days=30&siteId=SITE_ID

Continue with domain-specific pages

Drill into funnels, journeys, search, or revenue views.

Use analytics subpages for deep-dive diagnostics.

Open unified cohort report (V2)

Load retention, churn, and diagnostics in one cohort call.

GET /api/v1/analytics/cohort/:siteId?cohortType=first_visit&intervalType=day&startDate=2026-01-01&endDate=2026-01-31&periodCount=12

Open product analytics v2 drilldown

Load product analytics with mandatory productId and unified associations.

GET /api/v1/analytics/product/:siteId/overview?productId=<uuid>&days=30
GET /api/v1/analytics/product/:siteId/associations?productId=<uuid>&source=purchase&mode=all

Open category analytics v2 detail

Load category conversion and format revenue using response currency.

GET /api/v1/analytics/category/:siteId/conversion?categoryPath=/men/shoes&days=30

Overview + migration-sensitive endpoints

GET /api/v1/analytics/overview
GET /api/v1/analytics/activity-logs
GET /api/v1/analytics/dashboard-summary
GET /api/v1/analytics/events/breakdown
GET /api/v1/analytics/product/:siteId/catalog
GET /api/v1/analytics/product/:siteId/overview
GET /api/v1/analytics/product/:siteId/associations
GET /api/v1/analytics/product/:siteId/top
GET /api/v1/analytics/category/:siteId/top
GET /api/v1/analytics/category/:siteId/conversion

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`Authorization`	Required	`Bearer token`	All overview endpoints	Authenticated analytics access is mandatory.
`days`	Optional	`number`	overview/dashboard-summary/events breakdown	Lookback window for metric aggregation.
`siteId`	Optional	`uuid`	overview/activity/dashboard-summary/events breakdown	Scope metrics to single site; omit for organization view.
`limit`	Optional	`number`	activity-logs	Caps recent activity rows returned.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need top KPI snapshot	GET /api/v1/analytics/overview	Fast high-level performance status.
Need consolidated dashboard cards	GET /api/v1/analytics/dashboard-summary	Returns mixed-module summary in one call.
Need recent operational trace	GET /api/v1/analytics/activity-logs	Shows latest activity records for diagnosis.
Need event-type distribution	GET /api/v1/analytics/events/breakdown	Helps detect ingestion anomalies or traffic shifts.
Need conversion pipeline detail	Go to /analytics/funnels	Funnel pages provide step-wise conversion context.

Common Errors and Fixes

Overview metrics look lower than expected

Cause: Too narrow days window or siteId filter unintentionally applied.

Fix: Increase days and verify whether site-level or org-level scope is intended.

Activity logs endpoint returns small dataset

Cause: Low limit parameter or low event throughput in period.

Fix: Increase limit and confirm event ingestion pipeline is healthy.

403 on analytics endpoints

Cause: User role lacks analytics view permission.

Fix: Grant analytics permissions via role configuration.

Product analytics query fails after migration

Cause: Client still sends productItemCode or calls removed product v1 endpoints.

Fix: Switch to productId-based v2 endpoints and remove v1 route usage.

Dashboard summary disagrees with custom reports

Cause: Different time windows or filters across reports.

Fix: Standardize date and site filters before comparison.

Production Checklist

Overview and dashboard-summary are polled with consistent days/site filters.Required
Event breakdown is monitored for ingestion regressions.Required
Activity log retention assumptions are documented for operators.Required
Access is limited to users with analytics permission.Required
Product analytics consumers migrated to productId + associations + catalog + top routes.Required
Category conversion revenue formatting uses conversion.metrics.currency only.Required
Follow-up drilldown path is defined for each KPI anomaly.Required