Read analytics

Website analytics is served by three endpoints: query for engagement totals and dimension breakdowns, timeseries for values over time, and realtime for who is on the site right now.

Analytics requires the Pro plan or higher. On lower plans these endpoints return 403 with kind forbidden. See Plans and limits.

Prerequisites

An API key with any access role on the website, see Create an API key
A published website receiving traffic, see the Quickstart

Time ranges and filters

The query and timeseries endpoints take startAt and endAt as Unix epoch timestamps in milliseconds, and accept these optional filters as query parameters: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort.

Read engagement totals

GET /v1/websites/{websiteId}/analytics/query returns totals for the range.

Last 7 days of totals

curl -G 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/analytics/query' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  --data-urlencode 'startAt=1751328000000' \
  --data-urlencode 'endAt=1751932800000'

Response

{
  "pageviews": 4821,
  "visitors": 1930,
  "visits": 2214,
  "bounces": 871,
  "totaltime": 391244
}

Add a filter to scope the totals, for example --data-urlencode 'country=US'. A website with no recorded traffic returns the same shape with zeros.

Break down by dimension

Add dimension to the same endpoint to rank values of one dimension alongside the totals. dimension is one of: path, entry, exit, title, query, referrer, channel, domain, country, region, city, browser, os, device, language, screen, event, hostname, tag, distinctId. limit caps the rows (default 25, max 1000).

Top pages

curl -G 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/analytics/query' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  --data-urlencode 'startAt=1751328000000' \
  --data-urlencode 'endAt=1751932800000' \
  --data-urlencode 'dimension=path' \
  --data-urlencode 'limit=10'

Response (truncated)

{
  "pageviews": 4821,
  "visitors": 1930,
  "visits": 2214,
  "bounces": 871,
  "totaltime": 391244,
  "rows": [
    { "name": "/", "pageviews": 1811, "visitors": 902, "visits": 1004, "bounces": 388, "totaltime": 140212 },
    { "name": "/pricing", "pageviews": 640, "visitors": 411, "visits": 452, "bounces": 130, "totaltime": 48120 }
  ]
}

rows is present only when dimension is set, ranked by page views with full engagement totals per value.

Read a time series

GET /v1/websites/{websiteId}/analytics/timeseries returns one series bucketed by unit (year, month, day, hour, or minute). series selects which:

series=pageviews returns parallel pageviews and sessions arrays, one point per bucket. Optional compare (prev for the previous period, yoy for a year earlier) requests comparison data.
series=events returns tracked custom-event counts in events, one point per event name per bucket, shaped { "x": "<event>", "t": "<period>", "y": <count> }. compare is not valid here.

Optional timezone (an IANA name) controls bucket boundaries, and maxPoints (default 30, max 500) caps how many of the most recent time buckets are returned.

Daily pageviews

curl -G 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/analytics/timeseries' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  --data-urlencode 'startAt=1751328000000' \
  --data-urlencode 'endAt=1751932800000' \
  --data-urlencode 'series=pageviews' \
  --data-urlencode 'unit=day' \
  --data-urlencode 'timezone=America/New_York'

Response (truncated)

{
  "pageviews": [ { "x": "2026-07-01", "y": 612 }, { "x": "2026-07-02", "y": 748 } ],
  "sessions": [ { "x": "2026-07-01", "y": 251 }, { "x": "2026-07-02", "y": 300 } ]
}

Only the requested series’ fields are present. When a query produces more buckets than maxPoints, only the most recent buckets are returned and the response carries a truncated field with shown, total, and a hint. Request a coarser unit, a narrower range, or a larger maxPoints for full coverage.

Watch realtime activity

GET /v1/websites/{websiteId}/analytics/realtime takes no range and returns a compact snapshot of Umami’s trailing 30-minute realtime window:

Realtime snapshot

curl 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/analytics/realtime' \
  -H "Authorization: Bearer $CACTAL_API_KEY"

Response

{
  "views": 44,
  "visitors": 12,
  "events": 3,
  "countries": 5,
  "timestamp": "2026-07-08T15:04:05.000Z"
}

visitors is the distinct visitor count in that 30-minute window; timestamp is the snapshot time as ISO 8601. This is not directly comparable to the removed active endpoint, which counted distinct visitors over five minutes.

Troubleshooting

Symptom	Cause	Fix
`403` forbidden	The organization’s plan does not include analytics.	Upgrade to Pro or higher.
All-zero responses	No traffic recorded yet, or the website was published recently.	Confirm the website is published and receiving visits.
`400` on `compare`	`compare` sent with `series=events`.	Drop `compare`, or set `series=pageviews`.
Series buckets look shifted	Range timestamps are interpreted in UTC without a `timezone`.	Pass `timezone`, for example `America/New_York`.

Next steps

Plans and limits for what each plan includes
How Cactal works for where analytics sits in the platform

Get started

Core concepts

Guides

Build with agents

Platform

Read analytics

Prerequisites

Time ranges and filters

Troubleshooting

Next steps

​Prerequisites

​Time ranges and filters

​Troubleshooting

​Next steps

Prerequisites

Time ranges and filters

Troubleshooting

Next steps