Stats API: Query Pageview and Visitor Analytics Data

The Stats endpoint is the primary way to pull your analytics data out of TinyTrack programmatically. Use it to fetch aggregated pageview counts, unique visitor numbers, and top-performing pages for any site in your account over a flexible date range. All data is pre-aggregated — TinyTrack never exposes raw visitor-level data, keeping you GDPR and CCPA clean by design.

Get Site Stats

Retrieve aggregated analytics for a specific site. GET /v1/stats

Query Parameters

string

required

The unique ID of the site to query. Get this value from GET /v1/sites.

string

default:"30d"

The time period to aggregate data over. Accepted values:

Value	Description
`today`	From midnight today (UTC) through the current moment
`7d`	The last 7 full days
`30d`	The last 30 full days (default)
`custom`	A custom range defined by `date_from` and `date_to`

string

The start of a custom date range in YYYY-MM-DD format (e.g. 2024-02-01). Required when period=custom.

string

The end of a custom date range in YYYY-MM-DD format (e.g. 2024-02-28). Required when period=custom. Must be greater than or equal to date_from.

string

default:"both"

The metric(s) to return. Accepted values:

Value	Description
`pageviews`	Total pageview count only
`visitors`	Unique visitor count only
`both`	Both pageviews and unique visitors (default)

Example Requests

curl "https://api.tinytrack.io/v1/stats?site_id=site_abc123&period=7d" \
  -H "Authorization: Bearer tt_live_xxxxxxxxxxxx"

curl "https://api.tinytrack.io/v1/stats?site_id=site_abc123&period=custom&date_from=2024-02-01&date_to=2024-02-28" \
  -H "Authorization: Bearer tt_live_xxxxxxxxxxxx"

curl "https://api.tinytrack.io/v1/stats?site_id=site_abc123&period=30d&metric=pageviews" \
  -H "Authorization: Bearer tt_live_xxxxxxxxxxxx"

const params = new URLSearchParams({
  site_id: 'site_abc123',
  period: '7d'
});

const res = await fetch(`https://api.tinytrack.io/v1/stats?${params}`, {
  headers: {
    'Authorization': `Bearer ${process.env.TINYTRACK_API_KEY}`
  }
});

const { data } = await res.json();
console.log(`${data.pageviews} pageviews, ${data.unique_visitors} visitors`);

Example Response

{
  "data": {
    "pageviews": 12483,
    "unique_visitors": 4201,
    "top_pages": [
      { "path": "/blog/intro", "views": 3100 },
      { "path": "/pricing", "views": 1800 }
    ],
    "date_from": "2024-02-01",
    "date_to": "2024-02-07"
  }
}

Response Fields

integer

The total number of pageviews recorded in the requested period. Omitted when metric=visitors.

integer

The number of unique visitors counted in the requested period. TinyTrack counts visitors using a daily-salted, cookieless fingerprint — no personal data is stored or returned. Omitted when metric=pageviews.

array

An ordered array of the most-viewed pages in the requested period, from highest to lowest view count. Each entry in the array contains:

path (string) — the URL path (e.g. /blog/intro)
views (integer) — the pageview count for that path in the period

string

The start of the period actually used for the query, in YYYY-MM-DD format. Useful for confirming the resolved range when you used a named period like 7d.

string

The end of the period actually used for the query, in YYYY-MM-DD format.

Notes on Data Accuracy

TinyTrack filters bot and crawler traffic automatically before data reaches the Stats API, so pageview and visitor numbers reflect real human sessions. Because TinyTrack is cookieless, unique visitor counts use per-site, per-day salted identifiers — visitors are never tracked across sites or across days, keeping your analytics fully compliant with GDPR, CCPA, and PECR.

To build a dashboard or reporting tool on top of this endpoint, cache responses on your side for at least 60 seconds. Analytics data updates in real time, but polling faster than that provides no additional resolution and counts against your rate limit.

Overview

Endpoints

Stats API: Query Pageview and Visitor Analytics Data

Get Site Stats

Query Parameters

Example Requests

Example Response

Response Fields

Notes on Data Accuracy

​Get Site Stats

​Query Parameters

​Example Requests

​Example Response

​Response Fields

​Notes on Data Accuracy

Get Site Stats

Query Parameters

Example Requests

Example Response

Response Fields

Notes on Data Accuracy