API Reference

Web Metrics

Read endpoints for SquirrelMetrics web analytics. Use the secret key for authentication. Requires the Metrics module to be enabled. Useful for cross-validating totals against other analytics tools.

Get Web Analytics Summary

GET /api/v1/metrics/web Secret Key 30 req/min

Returns aggregated stats, chart data, and top breakdowns matching the /metrics/web dashboard.

Query Parameters

Parameter	Type	Description
period	string	One of `today`, `7d`, `30d`, `12m`. Defaults to `7d`.

Success Response (200)

{
  "period": "7d",
  "period_start": "2026-05-11T00:00:00+01:00",
  "period_end": "2026-05-18T10:00:00+01:00",
  "stats": {
    "unique_visitors": 1240,
    "total_visits": 1582,
    "pageviews": 4310,
    "views_per_visit": 2.7,
    "bounce_rate": 41
  },
  "chart_data": { "2026-05-11T00:00:00+01:00": 210, "...": 0 },
  "top_sources":           { "google.com": 412, "twitter.com": 81 },
  "top_pages":             { "/": 1820, "/pricing": 612 },
  "top_countries":         { "US": 720, "GB": 310 },
  "top_devices":           { "Desktop": 980, "Mobile": 540 },
  "top_browsers":          { "Chrome": 1100, "Safari": 320 },
  "top_operating_systems": { "Mac": 600, "Windows": 480 },
  "top_bots":              { "GoogleBot": 87 },
  "bot_count": 94
}

List Raw Visits

GET /api/v1/metrics/web/visits Secret Key 30 req/min

Paginated list of raw visits in the period. Excludes bots by default.

Query Parameters

Parameter	Type	Description
period	string	One of `today`, `7d`, `30d`, `12m`. Defaults to `7d`.
page	integer	1-indexed page number. Defaults to 1.
per_page	integer	Page size. Defaults to 100, max 1000.
include_bots	boolean	Set to `true` to include bot traffic.

Success Response (200)

{
  "period": "7d",
  "page": 1,
  "per_page": 100,
  "total": 1582,
  "visits": [
    {
      "id": 12345,
      "visit_token": "...",
      "visitor_token": "...",
      "started_at": "2026-05-18T09:14:22Z",
      "landing_page": "https://example.com/",
      "referrer": "https://google.com/search?q=...",
      "country": "US",
      "browser": "Chrome",
      "os": "Mac",
      "device_type": "Desktop",
      "bot_name": null,
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null
    }
  ]
}

List Raw Events

GET /api/v1/metrics/web/events Secret Key 30 req/min

Paginated list of raw events in the period. Excludes bot-owned events by default.

Query Parameters

Parameter	Type	Description
period	string	One of `today`, `7d`, `30d`, `12m`. Defaults to `7d`.
name	string	Filter by event name, e.g. `$page_view`.
page	integer	1-indexed page number. Defaults to 1.
per_page	integer	Page size. Defaults to 100, max 1000.
include_bots	boolean	Set to `true` to include events from bot visits.

Success Response (200)

{
  "period": "7d",
  "page": 1,
  "per_page": 100,
  "total": 4310,
  "events": [
    {
      "id": 9876,
      "visit_id": 12345,
      "name": "$page_view",
      "time": "2026-05-18T09:14:22Z",
      "properties": { "url": "https://example.com/", "title": "Home" }
    }
  ]
}

Errors

All three endpoints return 403 Forbidden if the Metrics module is disabled for the account:

{
  "error": "Metrics not enabled"
}