API
Query website analytics with the API
Query traffic, engagement and conversion-ready website metrics with bounded Premely API requests.
What it is
The analytics API provides a complete dashboard bundle and a focused query endpoint for overview, time series and breakdown results.
Why use it
Use it to power internal reporting, compare periods or analyse a single supported dimension without exporting raw events.
Before you start
- Create a token with
analytics:readand access to the site you want to query. - Use the site UUID returned by
GET /v1/sites, not the public domain or site key.
How to use it
- 1
Choose the endpoint
Use
/stats/dashboardfor the canonical dashboard bundle or/stats/queryfor selected metrics and one optional dimension. - 2
Set the reporting range
Choose a named range such as
28dor send an ordered pair of ISO 8601 timestamps. A range can cover no more than 366 days and cannot end in the future. - 3
Choose metrics and context
For a focused query, select one to seven supported metrics, one optional dimension and one optional single-value filter.
- 4
Check the result type
The response states whether the data is an overview, time series or breakdown. Treat an empty
visit_durationasnull, not zero.
Compare 28 days of analytics
This query requests core metrics and compares them with the immediately preceding period.
curl --request POST 'https://api.premely.io/v1/sites/SITE_ID/stats/query' \
--header "Authorization: Bearer $PREMELY_API_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"date_range": "28d",
"metrics": ["visitors", "visits", "pageviews", "bounce_rate"],
"compare": "previous_period"
}'Metrics and query controls
| Control | Supported values |
|---|---|
| Metrics | visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, events. |
| Named ranges | day, today, yesterday, realtime, 24h, 7d, 28d, 30d, 91d, month, last_month, 6mo, 12mo, year. |
| Time dimensions | time, time:hour, time:day, time:week, time:month. |
| Content dimensions | event:page, event:name. |
| Acquisition dimensions | visit:source, visit:referrer and supported visit:utm_* fields. |
| Audience dimensions | visit:country, visit:region, visit:city, visit:device, visit:browser, visit:os. |
| Filter operators | is, is_not, contains, contains_not. One filter with one value is supported per query. |
| Comparison | none, previous_period or year_over_year. |
Analytics constraints
- A focused query supports at most one dimension and one single-value filter.
- Non-time breakdowns return only
visitors,visits,pageviewsandevents. - Derived session metrics cannot be combined with an
event:*filter or a non-time breakdown. Premely returns422instead of changing the meaning of the request. - Dashboard requests reject
event:pageandevent:namefilters because the bundle includes session-derived metrics. - Exact ranges are limited to 366 days. Query pagination is limited to 100 rows per page and an offset of 10,000.
What to expect
Empty duration remains unknown
When there are no visits, visit_duration is null. Counts and valid rates can still be zero.
Suspicious traffic is explicit
Use include.include_suspicious to control whether suspicious traffic is included. The default is true.