Guides

App Analytics

Read owner-visible app traffic, route, path, referrer, auth, job, webhook, and error summaries.

For agents: Use GET /v0/apps/:app_id/analytics?range=7d|30d|90d for paid, owner-visible aggregate analytics. Treat 402 entitlement_required as an upgrade state and never expect visitor identity, full URLs, request bodies, cookies, authorization headers, or raw event timelines.

Overview

App Analytics helps platform account owners understand how their own published app is being served on Userland. It is an account feature, not an app manifest resource and not a customer-installed browser analytics script.

The analytics view combines aggregate gateway traffic rollups with existing owner-visible operational tables. It shows request volume, response health, route and runtime breakdowns, top app paths, referrer domains, app auth counts, job and webhook status counts, and recent error-level app events.

Access

Only platform account members who can read the app can read its analytics. App users, invitees, and runtime roles cannot access the control-plane analytics endpoint unless they are also platform account members with app read access.

The endpoint is paid-feature gated:

GET /v0/apps/:app_id/analytics?range=30d

Free accounts receive 402 entitlement_required. The console renders that response as an upgrade state instead of exposing analytics data.

Metrics Included

Traffic metrics include:

total requests
successful requests
error requests and error rate
request series by UTC day
status buckets such as 2xx, 3xx, 4xx, and 5xx
runtime target counts for static, server, and app-level not-found responses
route counts for canonical app origins, slug routes, and custom domains

Surface metrics include:

top normalized paths
top route hostnames or route identifiers
top referrer domains

Operational summaries include:

app-user signup counts when app-user auth is declared
app session creation counts
jobs by status
webhook deliveries by status
recent error-level app events

Retention

The requested range can be 7d, 30d, or 90d. Userland clamps the range to the account plan’s retention window.

Plan	App Analytics	Retention
Free	No dashboard; upgrade state only	None
Starter	Included	7 days
Business	Included	30 days
Business Plus	Included	90 days
Agency	Included	90 days
Internal	Included	90-day API view clamp

Rollup cleanup removes rows outside the retention window. New traffic appears after the app gateway serves eligible app-owned requests.

Privacy And Data Minimization

App Analytics stores aggregate rollups, not raw request or visitor timelines. Traffic rollups do not store app-user identity analytics, app-user email addresses, raw app-user IDs, session hashes, request bodies, cookies, authorization headers, or full request headers.

Path and referrer dimensions are normalized before storage:

query strings and fragments are stripped from paths
long, empty, invalid, or excessive path values are bucketed
referrers store domains only, not full referrer URLs
same-origin referrers can be grouped as internal traffic
missing or invalid referrers are bucketed

The analytics response also filters stored dimensions before returning them, so unexpected dimension fields are not exposed through the public API.

App Analytics Vs Platform Analytics

App Analytics is customer-owner-visible. It answers questions about a customer’s own published app: served traffic, top paths, referrers, response health, auth activity, jobs, webhooks, and runtime errors.

Platform Analytics is internal Userland measurement. It is used for Userland’s acquisition, activation, billing, retention, and product-quality analysis. App Analytics does not expose Platform Analytics events.

Troubleshooting Missing Data

If the Analytics tab is empty:

Confirm the account plan includes App Analytics.
Confirm the app has received traffic after analytics shipped.
Confirm the traffic reached an app-owned route, not /health, /healthz, an unresolved host, or a reserved /_userland/* route.
Check that the selected range fits the plan retention window.
Read recent app events for runtime failures:

userland apps events "$APP_ID" --severity error --limit 25

Analytics capture is best effort. Capture failures should not change the status or body served to app visitors.

Limitations

V1 does not include unique visitor counts, browser session analytics, funnels, customer app marketing attribution, raw request browsing, per-app-user timelines, configurable exports, bot filtering, or a customer-installed JavaScript analytics SDK.