Reports

The Reports API provides historical analytics data aggregated from collected events. All report endpoints accept a date range and return pre-aggregated metrics.

All endpoints require an OAuth 2.0 Bearer token.

Common Query Parameters

All report endpoints share these query parameters:

Parameter	Type	Required	Description
from	string	Yes	Start date (ISO 8601, e.g., 2026-03-01)
to	string	Yes	End date (ISO 8601, e.g., 2026-03-26). Must be on or after from.

Overview Report

Returns high-level metrics for the specified period.

GET /v1/analytics/reports/overview

Authentication: OAuth Bearer

Scope: insightcore:reports.read

Rate Limit: 100/min

Response

{
  "data": {
    "total_visitors": 12450,
    "total_page_views": 38920,
    "bounce_rate": 42.3,
    "avg_session_duration_seconds": 185
  }
}

Response Fields

Field	Type	Description
total_visitors	integer	Unique visitors in the period
total_page_views	integer	Total page views in the period
bounce_rate	number	Percentage of single-page sessions (0–100)
avg_session_duration_seconds	integer	Average session length in seconds

Pages Report

Returns per-page analytics, sorted by most viewed.

GET /v1/analytics/reports/pages

Authentication: OAuth Bearer

Scope: insightcore:reports.read

Rate Limit: 100/min

Response

{
  "data": [
    {
      "page_url": "https://mystore.com/",
      "views": 8450,
      "unique_visitors": 6200,
      "avg_time_on_page_seconds": 45,
      "bounce_rate": 38.2
    },
    {
      "page_url": "https://mystore.com/products",
      "views": 5320,
      "unique_visitors": 4100,
      "avg_time_on_page_seconds": 62,
      "bounce_rate": 25.1
    }
  ]
}

Response Fields

Field	Type	Description
page_url	string	Page URL
views	integer	Total page views
unique_visitors	integer	Distinct visitors
avg_time_on_page_seconds	integer	Average time spent on the page
bounce_rate	number	Bounce rate for this page (0–100)

Traffic Sources Report

Returns visitor counts broken down by referral source.

GET /v1/analytics/reports/traffic-sources

Authentication: OAuth Bearer

Scope: insightcore:reports.read

Rate Limit: 100/min

Response

{
  "data": [
    {
      "source": "google",
      "medium": "organic",
      "campaign": null,
      "visitors": 4500,
      "page_views": 12300
    },
    {
      "source": "facebook",
      "medium": "social",
      "campaign": "spring_sale",
      "visitors": 1200,
      "page_views": 3400
    },
    {
      "source": "(direct)",
      "medium": "(none)",
      "campaign": null,
      "visitors": 3800,
      "page_views": 8900
    }
  ]
}

Response Fields

Field	Type	Description
source	string	Traffic source (e.g., google, facebook, (direct))
medium	string	Traffic medium (e.g., organic, social, cpc, (none))
campaign	string|null	UTM campaign name, if present
visitors	integer	Unique visitors from this source
page_views	integer	Total page views from this source

Events Report

Returns event counts grouped by event type.

GET /v1/analytics/reports/events

Authentication: OAuth Bearer

Scope: insightcore:reports.read

Rate Limit: 100/min

Response

{
  "data": [
    {
      "event_type": "page_view",
      "event_name": null,
      "count": 38920
    },
    {
      "event_type": "click",
      "event_name": null,
      "count": 15430
    },
    {
      "event_type": "product_view",
      "event_name": null,
      "count": 8200
    },
    {
      "event_type": "add_to_cart",
      "event_name": null,
      "count": 3150
    },
    {
      "event_type": "purchase",
      "event_name": null,
      "count": 1200
    }
  ]
}

Response Fields

Field	Type	Description
event_type	string	Event type identifier
event_name	string|null	Specific event name, if applicable
count	integer	Total event occurrences in the period

Ecommerce Report

Returns ecommerce-specific metrics for the period.

GET /v1/analytics/reports/ecommerce

Authentication: OAuth Bearer

Scope: insightcore:reports.read

Rate Limit: 100/min

Response

{
  "data": {
    "total_revenue": 45230.50,
    "total_orders": 1200,
    "avg_order_value": 37.69,
    "conversion_rate": 2.85,
    "product_views": 8200,
    "add_to_cart_count": 3150,
    "checkout_count": 1800,
    "purchase_count": 1200
  }
}

Response Fields

Field	Type	Description
total_revenue	number	Sum of all order totals
total_orders	integer	Number of completed purchases
avg_order_value	number	Average order total (total_revenue / total_orders)
conversion_rate	number	Purchase conversion rate as a percentage of total sessions
product_views	integer	Total product view events
add_to_cart_count	integer	Total add-to-cart events
checkout_count	integer	Total checkout-initiated events
purchase_count	integer	Total completed purchase events

Caching Behavior

Report responses are cached server-side to optimize performance:

Data Age	Cache Duration
Less than 2 hours old	5 minutes
More than 24 hours old	1 hour

Cache keys are scoped to your organization and the specific query parameters. Responses always include the X-RateLimit-* headers described in Authentication.

---

Changelog

Date	Change
2026-03-26	Initial publication.