API Reference

Tally exposes a REST API at /api/v1/* . All endpoints require authentication via the Authorization header with a Bearer token (your API_KEY or ADMIN_PASSWORD ).

Authentication

curl -H "Authorization: Bearer your-api-key"   https://your-tally-server.com/api/v1/overview

Common parameters

All endpoints accept these query parameters:

site_id    # Site identifier (default: "blog")
period     # Time range: "1h", "7d", "30d", etc. (default: "7d")
start      # Custom start date (ISO 8601)
end        # Custom end date (ISO 8601)
limit      # Max results for list endpoints (default: 20, max: 100)

Endpoints

Overview metrics

GET /api/v1/overview?site_id=blog&period=7d

Returns total pageviews, unique visitors, bounce rate, average session duration, and returning visitor percentage for the period.

Top pages

GET /api/v1/pages?site_id=blog&period=7d&limit=20

Returns a list of pages sorted by view count, with unique views, average focus time, and average scroll depth.

Page engagement

GET /api/v1/pages/%2Fblog%2Fpost/engagement?site_id=blog&period=7d

Returns detailed engagement for a specific page: scroll depth distribution, average focus time, and next-page flow.

Traffic sources

GET /api/v1/sources?site_id=blog&period=7d&limit=20

Returns referrer breakdown with source, medium, and visit count.

Geo breakdown

GET /api/v1/geo?site_id=blog&period=7d&limit=20

Returns country, region, and city breakdowns with visit counts. Requires GeoIP setup.

Device breakdown

GET /api/v1/devices?site_id=blog&period=7d

Returns browser, OS, and device type breakdowns.

Pageviews over time

GET /api/v1/pageviews-over-time?site_id=blog&period=30d&granularity=day

Returns pageview counts bucketed by day or hour. Use granularity=hour for hourly data.

Insights

GET /api/v1/insights?site_id=blog&period=7d

Returns metric changes compared to the previous period — growth rates for pageviews, visitors, bounce rate, and session duration.

Realtime

GET /api/v1/realtime?site_id=blog

Returns current active visitors and which pages they're viewing. Based on pings received in the last 5 minutes.

Search

GET /api/v1/search?site_id=blog&q=blog&limit=10

Searches page paths and titles matching the query string.

CSV Export

Export pageviews

GET /api/v1/export/pageviews?site_id=blog&period=30d

Export sessions

GET /api/v1/export/sessions?site_id=blog&period=30d

Export pages summary

GET /api/v1/export/pages?site_id=blog&period=30d

All export endpoints return CSV files with Content-Disposition headers for download.