Analytics Platform
API Documentation
Documentation menu

Core analytics

Headline traffic metrics: aggregate stats, live visitors, pageview series and custom events.

4 endpoints, all relative to https://analytics.appfor.you. Shared rules live in Conventions, Rate limits and Error codes.

Aggregate stats

GET/api/v2/sites/{siteId}/statsscope: read

The best single call for "how is my site doing". Returns headline numbers plus the top 10 pages, referrers, browsers and countries for the window, and echoes the resolved window back as `range`. The numbers are computed with the same maths as the dashboard, so an agent and a human never see two different figures for the same site.

  • `avgDuration` is TOTAL time on site divided by UNIQUE VISITORS (a visitor is `visitorId`, falling back to `sessionId`) — not the mean of individual pageview durations. Rounded to one decimal.
  • `bounceRate` is a percentage of sessions, also rounded to one decimal.
  • This endpoint takes only the `range` preset — there are no `from`/`to` overrides here. The echoed `range` object reports the preset plus the exact window used.

Path parameters

siteIdstringThe Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere.

Query parameters

NameTypeDescription
rangestringRelative window: `7d`, `30d` or `90d`. Default `7d`.

Example request

curl -H "Authorization: Bearer $ANALYTICS_API_KEY" \
  "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/stats?range=30d"

Example response

{
  "visitors": 1234,
  "pageviews": 5678,
  "bounceRate": 42.3,
  "avgDuration": 145.7,
  "topPages": [
    { "pathname": "/", "views": 2000 },
    { "pathname": "/pricing", "views": 800 }
  ],
  "topReferrers": [
    { "referrer": "google.com", "count": 500 }
  ],
  "browsers": [
    { "browser": "Chrome", "count": 3000 }
  ],
  "countries": [
    { "country": "US", "count": 2000 }
  ],
  "range": {
    "preset": "30d",
    "since": "2025-02-19T00:00:00.000Z",
    "until": "2025-03-21T00:00:00.000Z"
  }
}

Real-time visitors

GET/api/v2/sites/{siteId}/realtimescope: read

A fixed 5-minute window — this endpoint takes no time-range parameter. Use it for live dashboards and "is anyone on the site right now" checks.

Path parameters

siteIdstringThe Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere.

Example request

curl -H "Authorization: Bearer $ANALYTICS_API_KEY" \
  "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/realtime"

Example response

{
  "activeVisitors": 42,
  "activePages": [
    { "path": "/", "visitors": 15 },
    { "path": "/pricing", "visitors": 8 }
  ]
}

Pageview detail

GET/api/v2/sites/{siteId}/pageviewsscope: read

Optionally filtered to a single pathname, which makes it the right call for "how did /pricing perform this month".

Path parameters

siteIdstringThe Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere.

Query parameters

NameTypeDescription
rangestringRelative window: `7d`, `30d` or `90d`. Default `7d`.
pathnamestringRestrict to a single page path, e.g. `/pricing`.

Example request

curl -H "Authorization: Bearer $ANALYTICS_API_KEY" \
  "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/pageviews?range=30d&pathname=/pricing"

Example response

{
  "total": 5678,
  "unique": 1234,
  "chart": [
    { "date": "2025-03-21", "count": 800 },
    { "date": "2025-03-22", "count": 920 }
  ]
}

Custom events

GET/api/v2/sites/{siteId}/eventsscope: read

Use this to discover which event names exist before creating an event-type goal or an alert.

Path parameters

siteIdstringThe Mongo _id returned as `siteId` by GET /api/v2/sites, or the public `trackingId` embedded in the tracking snippet. Both are accepted everywhere.

Query parameters

NameTypeDescription
rangestringRelative window: `7d`, `30d` or `90d`. Default `7d`.

Example request

curl -H "Authorization: Bearer $ANALYTICS_API_KEY" \
  "https://analytics.appfor.you/api/v2/sites/6507f1f77bcf86cd799439011/events?range=30d"

Example response

{
  "events": [
    { "name": "signup_click", "count": 234 },
    { "name": "download_pdf", "count": 89 }
  ]
}