Everything you need to install, configure, and query UserActivity.ai.
Three steps to start tracking:
<head><script
src="https://useractivity.ai/tracker.js"
data-site="YOUR_SITE_ID"
defer
></script>No npm packages, no build step, no configuration. The tracker loads asynchronously (<8KB gzipped), never blocks rendering, and works on any site — React, Vue, Svelte, vanilla HTML, Lovable, Vercel, anywhere.
Query behavioral data directly via HTTP. All analysis endpoints require a site_id query parameter and an Authorization: Bearer header with your API key. Find both in your dashboard.
# Quick test — get your site health score
curl -H "Authorization: Bearer YOUR_API_KEY" "https://useractivity.ai/api/v1/health?site_id=YOUR_SITE_ID"Each endpoint returns structured JSON with scores, breakdowns, and natural-language narratives — designed for AI agent consumption.
| Endpoint | Description |
|---|---|
| /api/v1/health | Overall site health — visitor counts, pageviews, top pages |
| /api/v1/frustration | Rage clicks, dead clicks, errors, hesitations — with frustration score |
| /api/v1/scroll | Scroll depth distribution, fold engagement, completion rates |
| /api/v1/session | Session reconstruction — duration tiers, page sequences, drop-offs |
| /api/v1/navigation | Navigation flow — common paths, entry/exit points, loops |
| /api/v1/engagement | Engagement metrics — return rate, time on page, interaction depth |
| /api/v1/summary | Stats + top pages as a markdown summary |
| /api/v1/context | Full behavioral context — all 5 scores + issues in one response |
GET /api/v1/frustration?site_id=YOUR_SITE_ID
Authorization: Bearer YOUR_API_KEY
{
"score": 72,
"score_breakdown": {
"rageClickPenalty": -8,
"deadClickPenalty": -12,
"errorPenalty": -3,
"hesitationPenalty": -5
},
"narratives": [
{
"severity": "warning",
"summary": "Dead clicks detected on /pricing",
"detail": "12% of sessions include clicks on non-interactive elements"
},
{
"severity": "critical",
"summary": "Rage clicks on checkout submit button",
"detail": "8% of sessions show 3+ rapid clicks on .btn-submit"
}
]
}GET /api/v1/context?site_id=YOUR_SITE_ID
Authorization: Bearer YOUR_API_KEY
// Returns all 5 analysis scores + top issues in a single response
// Ideal for giving your AI agent complete behavioral context| Endpoint | Description |
|---|---|
| GET /api/health | Service health check (no auth required) |
| GET /api/stats | Event statistics for a site (requires auth) |
| POST /api/events | Event ingestion (used by tracker — you don't call this directly) |
Connect your AI coding agent to live behavioral data via the Model Context Protocol. Nothing to install — your agent connects directly to the hosted server.
Add to your project's .mcp.json (Claude Code, Cursor, or any MCP-compatible agent):
{
"mcpServers": {
"useractivity": {
"type": "http",
"url": "https://useractivity.ai/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Find your API key in the dashboard under Setup. Works with Claude Code, Claude Desktop, Cursor, and any MCP client that supports HTTP transport.
Run the MCP server locally via npx (requires npm):
{
"mcpServers": {
"useractivity": {
"command": "npx",
"args": ["@useractivity/mcp-server"],
"env": {
"USERACTIVITY_API_KEY": "your-api-key",
"USERACTIVITY_SITE_ID": "your-site-id"
}
}
}
}| Tool | Description |
|---|---|
| get_site_health | Overall site health — visitor counts, pageviews |
| get_frustration_signals | Rage clicks, dead clicks, errors, hesitations |
| get_page_summary | Per-page behavioral summary |
| get_scroll_analysis | Scroll depth distributions and engagement |
| get_session_analysis | Session reconstruction and analysis |
| get_navigation_flow | Common paths, drop-offs, loops |
| get_engagement_metrics | Duration, return rate, interaction depth |
| get_form_analysis | Form interactions, abandonment, completion rates |
| get_page_comparison | Side-by-side behavioral comparison of two pages |
| Variable | Description |
|---|---|
| USERACTIVITY_API_KEY | Your site API key (found in dashboard Settings) |
| USERACTIVITY_SITE_ID | Your site ID (UUID, found in dashboard Settings) |
All commands support --format json for AI agent consumption via bash.
| Command | Description |
|---|---|
| npx useractivity status | Check tracking health — confirms events are flowing |
| npx useractivity health | Site health score with top issues ranked by severity |
| npx useractivity frustration | Rage clicks, dead clicks, form abandonment, U-turns |
| npx useractivity context | Generate .useractivity/context.md behavioral summary for AI agents |
All events are auto-captured. No event taxonomy to design, no custom tracking code to write.
| Event Type | Description |
|---|---|
| click | User clicks on any element — captures target, position, timestamp |
| rage_click | 3+ clicks within 2 seconds on the same target — signals frustration |
| dead_click | Click on a non-interactive element — signals confusing affordances |
| scroll | Scroll depth, velocity, direction changes, pause points |
| form_field_focus | User focuses a form field — tracks field index and type |
| form_field_blur | User leaves a form field — tracks time spent |
| form_submit | Form submission with fields completed vs. total count |
| form_abandon | User leaves page with incomplete form — captures abandonment field |
| navigation | Page transition — from/to pages, method (link, back button, direct) |
| error | JavaScript errors and failed network requests during session |
| hesitation | Prolonged hover (2s+) without click — signals confusion |
| u_turn | Back-button press or rapid navigation reversal — signals lost users |
UserActivity.ai is privacy-first by design. Anonymous behavioral patterns only.
Do Not Track: If navigator.doNotTrack === "1", the tracker does not initialize.
No cookies: Session ID uses crypto.randomUUID(), stored in sessionStorage (dies with the tab).
Data retention: Events auto-deleted after 90 days by default (configurable: 30, 60, 90, 180 days).
Escape hatch: Call window.useractivity.disable() to stop tracking programmatically.
Open source & source-available: The tracker is open source (MIT). Analytical tools are source-available (Elastic License 2.0). Audit exactly what data is collected and transmitted.