-
Notifications
You must be signed in to change notification settings - Fork 0
REST API
All analytics data is available via the WordPress REST API under the /wp-json/rsa/v1/ namespace. All read endpoints require the rsa_manage_statistics capability (administrator by default, also assigned to the custom Statistics Analyst role).
Use WordPress application passwords (WP 5.6+) for API access from external tools:
curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
https://example.com/wp-json/rsa/v1/overview
Within the WordPress admin, all requests are automatically authenticated via nonce.
Every endpoint returns a consistent JSON wrapper:
{
"ok": true,
"data": { /* endpoint-specific payload */ }
}
The examples below show the inner data object only for clarity.
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 30d |
Time range. One of: 7d, 30d, 90d, thismonth, lastmonth
|
Summary metrics for the selected period.
GET /wp-json/rsa/v1/overview?period=7d
{
"pageviews": 14823,
"sessions": 9241,
"unique_days": 7,
"bounce_rate": 0.42,
"avg_time_on_page": 87,
"top_page": "/blog/privacy-analytics/",
"period": { "from": "2025-01-01", "to": "2025-01-07" }
}
Top pages ranked by pageviews. Supports filtering and sorting.
GET /wp-json/rsa/v1/pages?period=30d&sort=avg_time&sort_dir=desc
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 30d |
Time range |
limit |
integer | 100 |
Max rows (1–100) |
browser |
string | — | Filter to a specific browser name |
os |
string | — | Filter to a specific OS name |
path |
string | — | Filter by path prefix (URL-encoded) |
sort |
string | views |
views or avg_time
|
sort_dir |
string | desc |
asc or desc
|
{
"pages": [
{ "page": "/blog/privacy-analytics/", "views": 3210, "avg_time": 87 },
{ "page": "/about/", "views": 1840, "avg_time": 58 }
]
}
Browser, OS, viewport, language, and timezone breakdowns.
GET /wp-json/rsa/v1/audience?period=7d
{
"by_browser": [ { "browser": "Chrome", "version": "120", "count": 5120 } ],
"by_os": [ { "label": "Windows", "count": 4900 } ],
"by_viewport": [ { "label": "1920×1080", "count": 3200 } ],
"by_language": [ { "label": "en-US", "count": 6100 } ],
"by_timezone": [ { "label": "America/New_York", "count": 2840 } ]
}
Traffic sources (domain-only, no paths or tokens).
GET /wp-json/rsa/v1/referrers?period=30d
{
"referrers": [
{ "domain": "google.com", "pageviews": 4120, "top_page": "/blog/article" },
{ "domain": "(direct)", "pageviews": 3980, "top_page": "/" }
]
}
Engagement metrics: time-on-page histogram, session depth distribution, and entry/exit pages.
GET /wp-json/rsa/v1/behavior?period=7d
{
"time_histogram": [ { "bucket": "0-9s", "count": 210 }, { "bucket": "30-59s", "count": 540 } ],
"session_depth": [ { "bucket": "1 page", "count": 320 }, { "bucket": "2 pages", "count": 180 } ],
"entry_pages": [ { "page": "/", "count": 820 } ]
}
UTM campaign performance: sessions and pageviews grouped by source / medium / campaign. Requires UTM parameters to be present on incoming links.
GET /wp-json/rsa/v1/campaigns?period=30d&medium=email
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 30d |
Time range |
limit |
integer | 100 |
Max rows (1–500) |
medium |
string | — | Filter to a specific UTM medium (e.g. email, cpc) |
{
"campaigns": [
{ "source": "newsletter", "medium": "email", "campaign": "march-digest", "sessions": 842, "pageviews": 1203 },
{ "source": "google", "medium": "cpc", "campaign": "spring-sale", "sessions": 540, "pageviews": 820 }
]
}
Step-based path flow showing how sessions progress through your site. Powers the Path Explorer in the admin and PWA.
GET /wp-json/rsa/v1/user-flow?period=30d&steps=4
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 30d |
Time range |
steps |
integer | 4 |
Depth of steps to return (2–5) |
entry_source |
string | — | Filter to sessions starting from this entry page |
focus_page |
string | — | Center the flow on a specific page path |
min_sessions |
integer | 1 |
Minimum session count to include a path node |
Also available: GET /user-flow/journey (page-to-page transition pairs) and GET /user-flow/sources (entry page breakdown).
Click events aggregated by element and protocol. The href_value field contains the actual destination: phone number for tel:, email address for mailto:, coordinates for geo:, SMS number for sms:, or file path for downloads.
GET /wp-json/rsa/v1/clicks?period=30d
{
"clicks": [
{
"href_protocol": "tel",
"element_tag": "a",
"element_text": "Call us",
"href_value": "+15551234567",
"count": 42
},
{
"href_protocol": "mailto",
"element_tag": "a",
"element_text": "Email us",
"href_value": "hello@example.com",
"count": 18
}
]
}
Click-position data for a specific page, used to render the heatmap overlay in the admin.
GET /wp-json/rsa/v1/heatmap?period=30d&page=/about/
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 30d |
Time range |
page |
string | / |
Page path to load click data for |
date_from |
string | — | Override start date (YYYY-MM-DD); takes precedence over period
|
date_to |
string | — | Override end date (YYYY-MM-DD) |
WooCommerce conversion funnel, revenue, and top-product data. Returns woocommerce_active: false when WooCommerce is not installed on the site rather than an error, so the PWA can show an appropriate message.
GET /wp-json/rsa/v1/woocommerce?period=30d
{
"woocommerce_active": true,
"funnel": {
"views": 4210,
"cart": 1830,
"orders": 412
},
"orders_count": 412,
"revenue_total": 18340.00,
"revenue_by_day": [
{ "day": "2026-03-01", "revenue": "610.00" },
{ "day": "2026-03-02", "revenue": "840.50" }
],
"top_products_viewed": [
{ "product_id": 42, "product_name": "Blue Widget Pro", "views": 1820 }
],
"top_products_cart": [
{ "product_id": 42, "product_name": "Blue Widget Pro", "total_qty": 390, "events": 812 }
]
}
Requires an active Premium licence. Returns `{ "woocommerce_active": false }` when WooCommerce is not installed; returns a 403 on free-tier installs.
Ingest a pageview event from the frontend tracker.
POST /wp-json/rsa/v1/track
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
string | yes | Page path |
session_id |
string | yes | Tab-scoped session UUID |
bot_signals |
integer | yes | Client-side bot detection bitmask |
referrer |
string | no | Referrer URL |
viewport |
string | no | Viewport dimensions (e.g. 1920x1080) |
language |
string | no | Browser language |
timezone |
string | no | IANA timezone |
utm_source |
string | no | UTM source |
utm_medium |
string | no | UTM medium |
utm_campaign |
string | no | UTM campaign |
screen |
string | no | Screen resolution |
time_on_page |
integer | no | Time spent on previous page (seconds) |
Available filter values for browser, OS, and page paths.
GET /wp-json/rsa/v1/filter-options
Retrieve user preferences (site list, theme, etc.).
GET /wp-json/rsa/v1/user-settings
Save user preferences.
POST /wp-json/rsa/v1/user-settings
| Parameter | Type | Required | Description |
|---|---|---|---|
sites |
array | no | Array of site objects {url, label, color}
|
theme |
string | no |
light or dark
|
The sites array is limited to 100 entries.
Structured analytics data for the AI assistant.
POST /wp-json/rsa/v1/ai/tool
| Parameter | Type | Required | Description |
|---|---|---|---|
tool |
string | yes | Tool name: overview, pages, audience, referrers, behavior, campaigns, user-flow, clicks, heatmap, woocommerce
|
params |
object | no | Tool-specific parameters (period, filters, etc.) |
Free tools: overview, pages, audience, referrers, behavior
Premium tools: campaigns, user-flow, clicks, heatmap, woocommerce
Delete all event data for a specific page path.
POST /wp-json/rsa/v1/purge-page
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
string | yes | Page path to purge |
Export raw event data for the given period. Returns JSON by default; pass format=csv to download a CSV file with a Content-Disposition header.
GET /wp-json/rsa/v1/export?period=90d&format=csv&data_type=pageviews
| Parameter | Type | Default | Description |
|---|---|---|---|
period |
string | 30d |
Time range preset |
format |
string | json |
json or csv
|
data_type |
string | pageviews |
pageviews, sessions, clicks, or referrers
|
date_from |
string | — | Custom start date (YYYY-MM-DD); overrides period
|
date_to |
string | — | Custom end date (YYYY-MM-DD) |
| HTTP status | Code | When |
|---|---|---|
| 401 | rest_not_logged_in |
No authentication provided |
| 403 | rest_forbidden |
Authenticated but lacks rsa_manage_statistics
|
| 400 | invalid_period |
Unrecognised period value |
- Home
- Release Tracks — Branch structure, promotion flows
- CI/CD Reference — Workflows, Freemius, deployment
- App Server Setup — Server infrastructure
- Code Map — Project structure