Site Analytics (totalum-sdk/analytics)

import … from 'totalum-sdk/analytics' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

Your site's own traffic: page views, visits, unique visitors, errors, bytes and response times, as a time series or a top list (top pages, referrers, countries, devices, browsers). Use it for a stats page in your app's admin. Free.

const { top } = await totalum.analytics.site({ dimension: 'path', metric: 'page_views', limit: 10 });

#totalumAnalytics

totalumAnalytics(options?: TotalumClientOptions): TotalumAnalytics

Creates the analytics namespace (the same object as totalum.analytics, scope analytics:read): the site's own traffic. Free.

Parameters

Returns TotalumAnalytics — The analytics namespace: the method below.

Example

import { totalumAnalytics } from 'totalum-sdk/analytics';

const analytics = totalumAnalytics();
const { series } = await analytics.site({ metric: 'page_views', granularity: 'day' });

The namespace's type is exported as TotalumAnalytics (import type { TotalumAnalytics } from 'totalum-sdk/analytics').

#analytics.site

analytics.site(q?: SiteAnalyticsQuery): Promise<SiteAnalyticsOutput>

The site's traffic: page views, hits, unique visitors, errors, bytes or response time (TTFB), as a time series (no dimension) or a top list by path, referrer, country, device, browser, OS, status or hostname. Counts come from sampled hits, so very small numbers are approximate. Free.

Parameters

Returns Promise<SiteAnalyticsOutput> — series (a time series) or top (a top list), the window used and when the numbers were computed.

Errors — besides the errors every call can throw:

Examples

const { series } = await totalum.analytics.site({ metric: ['page_views', 'uniques'], granularity: 'day' });

Result:

{
  "series": [
    { "t": "2026-10-09T00:00:00.000Z", "page_views": 412, "uniques": 128 },
    { "t": "2026-10-10T00:00:00.000Z", "page_views": 538, "uniques": 171 }
  ],
  "window": { "from": "2026-10-04T17:39:00.000Z", "to": "2026-10-11T17:39:00.000Z", "granularity": "day" },
  "source": "wae",
  "approximate": { "uniques": true },
  "cachedAt": "2026-10-11T17:38:40.720Z"
}

const { top } = await totalum.analytics.site({ dimension: 'path', metric: 'page_views', limit: 3 });

Result:

{
  "top": [
    { "key": "/", "share": 0.41, "page_views": 1210 },
    { "key": "/pricing", "share": 0.18, "page_views": 532 },
    { "key": "/blog/launch", "share": 0.07, "page_views": 207 }
  ],
  "window": { "from": "2026-10-04T17:39:00.000Z", "to": "2026-10-11T17:39:00.000Z", "granularity": "day" },
  "source": "wae",
  "approximate": { "uniques": false },
  "cachedAt": "2026-10-11T17:38:41.388Z"
}

#SiteAnalyticsOutput

The answer of analytics.site().

#SiteAnalyticsQuery

What analytics.site() reads: the window, the metrics and, for a top list, the dimension; all optional.

#SiteDimension

What a top list of analytics.site() groups by.

#SiteMetric

What analytics.site() counts.