API Reference
The worker exposes five endpoints. Authentication is only required on /query.
POST /track
POST /track
Records an analytics event. Called automatically by the tracking script. Auth: CORS origin check against ALLOWED_ORIGINS.
| Field | Type | Description | |
|---|---|---|---|
| event | string | required | Event name: pageview, outbound, timing, scroll_depth, or custom |
| path | string | required | Page path (e.g. /blog/post) |
| referrer | string | optional | Referrer hostname or "direct" |
| props | object | optional | Custom event properties (key/value pairs) |
| utm_source | string | optional | UTM source parameter |
| utm_medium | string | optional | UTM medium parameter |
| utm_campaign | string | optional | UTM campaign parameter |
GET /query
GET /query
Runs a predefined analytics query against Cloudflare Analytics Engine. Requires X-API-Key header matching QUERY_API_KEY.
Returns { data: [...] } — an array of result rows.
Traffic
top-pages
Top pages by view count
top-pages-visitors
Top pages by unique visitors
top-pages-stories
Top pages with engagement metrics
daily-views
Pageviews per day
daily-unique-visitors
Unique visitors per day
new-vs-returning
New vs returning visitor ratio
total-sessions
Total session count in period
Referrers
referrers
Traffic sources by hostname
referrers-by-page?page=/path
Referrers for a specific page
utm-campaigns
UTM campaign performance
utm-campaign-trend
Campaign traffic over time
utm-by-page?page=/path
UTM breakdown for a specific page
Content
page-views-over-time?page=/path
Views over time for a specific page
page-timing
Average time on page
timing-by-page?page=/path
Time on page per URL
bounce-rate-by-page?event_name=seconds
Bounce rate per page
scroll-depth
Scroll milestone aggregates (25/50/75/100%)
scroll-depth-by-page
Scroll depth broken down by page
scroll-depth-for-page?page=/path
Scroll depth for a specific page
Geo & Devices
countries
Visitors by country code
countries-by-page?page=/path
Country breakdown for a specific page
devices
Device type split (mobile/tablet/desktop)
browsers
Browser breakdown
Conversions
outbound-links
External link clicks with destinations
page-performance
Combined traffic + engagement per page
custom-events
Custom event counts and properties
conversion-funnel
Multi-step funnel completion rates
funnel-by-event?event_name=signup
Funnel analysis for a specific event
Live (30-min window)
live-visitors
Active visitors in the last 30 minutes
live-pages
Active pages in the last 30 minutes
live-referrers
Active referrers in the last 30 minutes
hourly-today
Today's traffic broken down by hour
Bot Traffic
bot-hits
Bot requests by user-agent
bot-hits-total
Total bot hit count in period
bot-pages
Pages most targeted by bots
bot-daily
Bot traffic per day
bot-countries
Bot traffic by country
Query parameters
| Parameter | Values | Description | |
|---|---|---|---|
| q | required | see above | Query name |
| site | required | hostname | Site hostname, e.g. mysite.com |
| period | required | 7d 14d 30d 60d 90d 180d | Time window for the query |
| page | optional | /path | Filter to a specific page path |
| event_name | optional | string | Filter by custom event name |
Examples
curl
# Top pages, last 30 days
curl -H "X-API-Key: $KEY" \
"https://worker.workers.dev/query?q=top-pages&period=30d&site=mysite.com"
# Response
{ "data": [
{ "path": "/blog/post", "views": 842 },
{ "path": "/", "views": 601 }
] }
curl
# Countries breakdown
curl -H "X-API-Key: $KEY" \
"https://worker.workers.dev/query?q=countries&period=7d&site=mysite.com"
# Response
{ "data": [
{ "country": "US", "visitors": 412 },
{ "country": "DE", "visitors": 98 }
] }
curl
# Funnel for a specific custom event
curl -H "X-API-Key: $KEY" \
"https://worker.workers.dev/query?q=funnel-by-event&event_name=signup&period=30d&site=mysite.com"
Other endpoints
GET /tracker.js
Serves the auto-configured tracking script. No auth required. The script reads its own URL to determine the worker endpoint.
GET /health
Returns {"status":"ok"}. No auth required. Use for uptime monitoring.
GET /config
Returns available query names and event types. No auth required.
Was this page helpful?