Endpoints

All endpoints are under the base URL https://app.statalog.com/api/v1 (Cloud) or https://your-domain.com/api/v1 (self-hosted). Every request must be authenticated — see Authentication for details.

Common parameters

These parameters are accepted by most endpoints:

Parameter	Type	Required	Description
site_id	string	Yes	Your site ID, e.g. ST-A1B2C3
from	string	No	Start date in YYYY-MM-DD format
to	string	No	End date in YYYY-MM-DD format
period	string	No	Shorthand period: 30d, 7d, or 1d. Used when from/to are not set

When neither from/to nor period is provided, the endpoint defaults to the last 30 days.

---

1. GET /api/v1/stats

Returns summary metrics for the specified period: total visitors, pageviews, sessions, bounce rate, and average session duration.

Parameters

All common parameters. No endpoint-specific parameters.

Example request

curl https://app.statalog.com/api/v1/stats \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d"

Example response

{
  "visitors": 14230,
  "pageviews": 38104,
  "sessions": 17891,
  "bounce_rate": 54.2,
  "avg_duration": 127
}

avg_duration is in seconds. bounce_rate is a percentage (0–100).

---

2. GET /api/v1/stats/timeseries

Returns the same summary metrics broken down by day, producing a time series suitable for charting.

Parameters

All common parameters. No endpoint-specific parameters.

Example request

curl https://app.statalog.com/api/v1/stats/timeseries \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "from=2025-04-01" \
  -d "to=2025-04-07"

Example response

{
  "timeseries": [
    { "date": "2025-04-01", "visitors": 1840, "pageviews": 4921, "sessions": 2103 },
    { "date": "2025-04-02", "visitors": 2210, "pageviews": 5887, "sessions": 2504 },
    { "date": "2025-04-03", "visitors": 1975, "pageviews": 5340, "sessions": 2271 },
    { "date": "2025-04-04", "visitors": 2090, "pageviews": 5612, "sessions": 2388 },
    { "date": "2025-04-05", "visitors": 1650, "pageviews": 4410, "sessions": 1890 },
    { "date": "2025-04-06", "visitors": 1430, "pageviews": 3820, "sessions": 1640 },
    { "date": "2025-04-07", "visitors": 1910, "pageviews": 5104, "sessions": 2180 }
  ]
}

---

3. GET /api/v1/pages

Returns the top pages ranked by pageviews, with per-page engagement metrics.

Parameters

Parameter	Type	Description
limit	integer	Number of pages to return. Default 20, maximum 100

Plus all common parameters.

Example request

curl https://app.statalog.com/api/v1/pages \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=7d" \
  -d "limit=5"

Example response

{
  "pages": [
    {
      "url": "/blog/how-to-use-statalog",
      "pageviews": 4210,
      "visitors": 3890,
      "bounce_rate": 48.1,
      "avg_duration": 183
    },
    {
      "url": "/",
      "pageviews": 3102,
      "visitors": 2980,
      "bounce_rate": 61.4,
      "avg_duration": 74
    },
    {
      "url": "/pricing",
      "pageviews": 1840,
      "visitors": 1790,
      "bounce_rate": 39.8,
      "avg_duration": 112
    }
  ]
}

---

4. GET /api/v1/referrers

Returns the top referrers — the external sources that sent visitors to your site.

Parameters

All common parameters. No endpoint-specific parameters.

Example request

curl https://app.statalog.com/api/v1/referrers \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d"

Example response

{
  "referrers": [
    { "source": "google.com", "visitors": 5840, "sessions": 6210 },
    { "source": "twitter.com", "visitors": 1230, "sessions": 1380 },
    { "source": "news.ycombinator.com", "visitors": 980, "sessions": 1040 },
    { "source": "Direct / None", "visitors": 3900, "sessions": 4120 }
  ]
}

Direct / None represents visits with no referrer header — bookmarks, typed URLs, and most dark social traffic.

---

5. GET /api/v1/channels

Returns traffic grouped by marketing channel (Organic Search, Direct, Social, Referral, Email, Paid Search, etc.).

Parameters

All common parameters. No endpoint-specific parameters.

Example request

curl https://app.statalog.com/api/v1/channels \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d"

Example response

{
  "channels": [
    { "channel": "Organic Search", "visitors": 6120, "sessions": 6890 },
    { "channel": "Direct", "visitors": 3900, "sessions": 4120 },
    { "channel": "Social", "visitors": 2140, "sessions": 2380 },
    { "channel": "Referral", "visitors": 1430, "sessions": 1540 },
    { "channel": "Email", "visitors": 640, "sessions": 710 }
  ]
}

---

6. GET /api/v1/locations

Returns visitor counts broken down by country.

Parameters

All common parameters. No endpoint-specific parameters.

Example request

curl https://app.statalog.com/api/v1/locations \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d"

Example response

{
  "locations": [
    { "country": "United States", "country_code": "US", "visitors": 5210 },
    { "country": "United Kingdom", "country_code": "GB", "visitors": 1840 },
    { "country": "Germany",        "country_code": "DE", "visitors": 1120 },
    { "country": "Canada",         "country_code": "CA", "visitors": 980 },
    { "country": "Australia",      "country_code": "AU", "visitors": 760 }
  ]
}

country_code is the ISO 3166-1 alpha-2 code, suitable for use with map libraries.

---

7. GET /api/v1/devices

Returns visitor counts broken down by device type, browser, or operating system. The breakdown is controlled by the breakdown parameter.

Parameters

Parameter	Type	Description
breakdown	string	One of device_type, browser, or os. Default: device_type

Plus all common parameters.

Example request

# Device type breakdown (default)
curl https://app.statalog.com/api/v1/devices \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d"

# Browser breakdown
curl https://app.statalog.com/api/v1/devices \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d" \
  -d "breakdown=browser"

Example response (device_type)

{
  "breakdown": "device_type",
  "devices": [
    { "name": "Desktop", "visitors": 8410 },
    { "name": "Mobile",  "visitors": 5190 },
    { "name": "Tablet",  "visitors": 630 }
  ]
}

Example response (browser)

{
  "breakdown": "browser",
  "devices": [
    { "name": "Chrome",  "visitors": 7820 },
    { "name": "Safari",  "visitors": 3640 },
    { "name": "Firefox", "visitors": 1490 },
    { "name": "Edge",    "visitors": 1280 }
  ]
}

---

8. GET /api/v1/events

Returns custom events recorded via statalog('event', ...) calls, showing each event name and its total count.

Parameters

Parameter	Type	Description
name	string	Filter to a single event name. Omit to return all events

Plus all common parameters.

Example request

# All events
curl https://app.statalog.com/api/v1/events \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d"

# Single event
curl https://app.statalog.com/api/v1/events \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d" \
  -d "name=Signup"

Example response

{
  "events": [
    { "name": "Signup",       "count": 842 },
    { "name": "Purchase",     "count": 314 },
    { "name": "Demo Request", "count": 127 },
    { "name": "Video Play",   "count": 2940 }
  ]
}

---

9. GET /api/v1/campaigns

Returns UTM-tagged campaign traffic broken down by source, medium, and campaign name.

Parameters

All common parameters. No endpoint-specific parameters.

Example request

curl https://app.statalog.com/api/v1/campaigns \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3" \
  -d "period=30d"

Example response

{
  "campaigns": [
    {
      "source":   "newsletter",
      "medium":   "email",
      "campaign": "april-product-update",
      "visitors": 1240,
      "sessions": 1380
    },
    {
      "source":   "google",
      "medium":   "cpc",
      "campaign": "brand-search",
      "visitors": 890,
      "sessions": 940
    }
  ]
}

Rows are only present for sessions that had all three UTM parameters set (utm_source, utm_medium, utm_campaign). Sessions with only partial UTM tags are not included.

---

10. GET /api/v1/live

Returns the number of visitors currently active on your site — defined as visitors who have sent a pageview in the last 5 minutes.

Parameters

Parameter	Type	Description
site_id	string	Required. Your site ID

No date range parameters apply; this endpoint always reflects the current moment.

Example request

curl https://app.statalog.com/api/v1/live \
  -H "Authorization: Bearer st_..." \
  -G \
  -d "site_id=ST-A1B2C3"

Example response

{
  "live": 42
}

Poll this endpoint at a reasonable interval (no more than once every 30 seconds) to build a live visitor counter. More frequent polling provides no additional accuracy and increases server load unnecessarily.

---

Error responses

All endpoints return standard HTTP status codes alongside a JSON error body:

Status	Meaning
401	Authentication failed — key missing, invalid, or revoked
422	Validation error — site_id missing or parameters invalid
404	Site not found or not accessible with this key
429	Rate limit exceeded
500	Internal server error

{ "error": "Unauthorized" }
{ "error": "The site_id field is required." }
{ "error": "Site not found." }