Stats API

Base URL: https://analytics.bitgate.dev. OpenAPI document | Authentication

TypeScript examples run server-side in Node 20+: save a snippet as example.mts, set any referenced environment variables, then run npx tsx example.mts.

Read a public report

GET /api/sites/{hostname}/overview

These examples only read demo.bitgate.dev. The curl example uses the default trailing 30 days; the TypeScript example selects the last 24 complete UTC hours.

curl --fail-with-body --silent --show-error --max-time 20 \
  'https://analytics.bitgate.dev/api/sites/demo.bitgate.dev/overview?tz=UTC'

const to = Math.floor(Date.now() / 3_600_000) * 3_600;
const query = new URLSearchParams({
  from: String(to - 86_400),
  to: String(to),
  tz: "UTC",
});
const response = await fetch(
  `https://analytics.bitgate.dev/api/sites/demo.bitgate.dev/overview?${query}`,
  { signal: AbortSignal.timeout(20_000) },
);
if (!response.ok) {
  throw new Error(`Overview ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Private reads add Authorization: Bearer <Firebase ID token>. Product API responses have no cross-origin CORS headers: use a server-side client or the Totallytics origin, even for public reports.

Date ranges

The overview and breakdown endpoints share the same range parser.

The rounded range must satisfy from < to and span no more than 400 days. Send seconds, not JavaScript milliseconds. Missing, empty, zero or non-numeric from/to values select their defaults rather than returning a validation error. Non-finite values or an invalid range return 400 invalid range.

Timezone handling

Use UTC or a recognized zone such as Europe/Amsterdam. The parser accepts at most two slash-separated components, each 1–32 characters of letters, digits, _, + or -. Other syntax silently becomes UTC; this includes multi-slash names such as America/Argentina/Buenos_Aires. A syntactically accepted but unknown zone can return 500 internal error.

Daily series timestamps are generated by converting a grouped calendar date to Unix seconds. They are not guaranteed to represent midnight in the requested timezone. Use tz=UTC for unambiguous date labels; the account summary returns explicit YYYY-MM-DD day strings.

Hour boundaries

Overview pageviews, visitors and series filter complete hourly aggregates by their hour's start. A range starting at 10:30 excludes the 10:00 bucket; an end at 11:30 includes the whole 11:00 bucket. Use UTC hour-aligned bounds when comparing these numbers with breakdowns, which filter individual timestamps.

Duration and scroll averages use individual append timestamps. The previous period applies the same rules to the immediately preceding interval of equal length.

Overview response

Example response:

{
  "totals": {
    "pageviews": 3,
    "visitors": 2,
    "avg_duration_s": 42,
    "avg_scroll": 75
  },
  "previous": {
    "pageviews": 2,
    "visitors": 2,
    "avg_duration_s": 30,
    "avg_scroll": 50
  },
  "series": [
    { "t": 1789516800, "pageviews": 1, "visitors": 1 },
    { "t": 1789520400, "pageviews": 2, "visitors": 2 }
  ],
  "live": 0,
  "granularity": "hour"
}

What the counts mean

• Visitor identifiers depend on the UTC day, site, request IP and user agent. They rotate daily, so a person returning tomorrow is not deduplicated across days. The supplied collector unique flag does not determine these visitor counts.
• Overview visitors use an approximate distinct aggregate. Breakdown visitors and live use exact distinct identifiers. These are identifiers, not a count of identified people or sessions.
• live is independent of the selected date range and includes pageview, event, append and error activity. Event-only visitors can appear live without increasing pageview visitors.
• Append averages are per append row, not per pageview or session. Appends are not joined back to pageviews for these calculations; repeated appends and zero-valued rows contribute to the mean in their own ingestion-time range.
• Series may be empty, omit quiet intervals, or contain a zero-pageview bucket created by append activity. Zero-fill in your client only if your chart needs it. Do not add bucket visitor counts to obtain a deduplicated range total.

Breakdowns

GET /api/sites/{hostname}/breakdown

tz has no effect on this endpoint. Rows are ordered by count descending. There is no cursor, offset, total-row count or metadata filter.

All breakdowns exclude bot rows. Blank values are omitted except for pages and referrers, where an empty value is named Direct / none. Event metadata is stored by the collector but cannot be retrieved, grouped or filtered through this API. utm_term and utm_content are not breakdown dimensions.

curl --fail-with-body --silent --show-error --max-time 20 \
  'https://analytics.bitgate.dev/api/sites/demo.bitgate.dev/breakdown?dim=pages&limit=10'

const query = new URLSearchParams({ dim: "pages", limit: "10" });
const response = await fetch(
  `https://analytics.bitgate.dev/api/sites/demo.bitgate.dev/breakdown?${query}`,
  { signal: AbortSignal.timeout(20_000) },
);
if (!response.ok) {
  throw new Error(`Breakdown ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Success is 200 with { "rows": [...] }. Each row has name (string), value (number of matching rows) and visitors (exact distinct visitor identifiers within that group). An empty report returns { "rows": [] }. A visitor can appear in several groups; group visitors must not be summed as a unique total.

All-sites summary

GET /api/sites/summary?tz=UTC

Requires a Firebase ID token even when some owned sites are public. Returns all sites owned by that account, ordered by creation time, with a rolling window beginning 31 days ago and an independent five-minute live count. Only tz is read; from, to and limit do not customize this endpoint.

curl --fail-with-body --silent --show-error --max-time 20 \
  -H "Authorization: Bearer ${TT_TOKEN:?Copy a token from Authentication}" \
  'https://analytics.bitgate.dev/api/sites/summary?tz=UTC'

const token = process.env.TT_TOKEN;
if (!token) throw new Error("Set TT_TOKEN from the Authentication page");

const response = await fetch(
  "https://analytics.bitgate.dev/api/sites/summary?tz=UTC",
  {
    headers: { Authorization: `Bearer ${token}` },
    signal: AbortSignal.timeout(20_000),
  },
);
if (!response.ok) {
  throw new Error(`Summary ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Sites without activity remain present with days: [] and live: 0. The rolling cutoff can give a partial first day; this is not 31 complete calendar days. The same timezone parser and hourly-boundary caveats apply.

Errors

Errors are JSON: { "error": "message" }. Successful JSON responses and handled errors carry Cache-Control: no-store.

Site access is checked before range or dimension validation. Public reports ignore a missing or invalid token because public access is sufficient. Site lookup caching can delay visibility changes.