Usage API

All endpoints require executive access level.

Analytics Engine Column Mapping

Events are stored in Cloudflare Analytics Engine with generic field names. The mapping:

Alias	AE Field	Type	Description
event_type	blob1	string	"page_view" or "feature_use"
path	blob2	string	Page/route path
user_id	blob3	string	Authenticated user ID
access_level	blob4	string	User role
feature	blob5	string	Feature name (e.g. "create_deal")
tool	blob6	string	Tool area (e.g. "deals")
metadata	blob7	string	JSON-encoded extra data
duration	double1	number	Time on page (seconds)

GET /api/usage/summary

Returns top-level statistics for the specified period.

Query parameters: days (7/14/30), user_id (optional)

Response:

{
  "total_page_views": 1234,
  "active_users": 12,
  "avg_duration": 45,
  "total_feature_uses": 567
}

GET /api/usage/top-pages

Returns the 10 most visited pages.

Query parameters: days, user_id (optional)

Response:

{
  "pages": [
    { "path": "/deals", "views": 150, "unique_users": 8, "avg_duration": 32 }
  ]
}

GET /api/usage/top-features

Returns the 10 most used features.

Query parameters: days, user_id (optional)

Response:

{
  "features": [
    { "feature": "create_deal", "tool": "deals", "uses": 45, "unique_users": 6 }
  ]
}

GET /api/usage/daily-trend

Returns daily aggregated counts for charting.

Query parameters: days, user_id (optional)

Response:

{
  "trend": [
    { "date": "2026-03-10", "page_views": 120, "feature_uses": 45, "active_users": 8 }
  ]
}

GET /api/usage/active-users

Returns the 20 most active users with enriched profile data.

Query parameters: days

Response:

{
  "users": [
    {
      "user_id": "abc",
      "user_name": "Alice",
      "user_picture": "https://...",
      "total_events": 200,
      "page_views": 150,
      "feature_uses": 50
    }
  ]
}

GET /api/usage/events

Returns recent events for the activity stream. Auto-enriched with user names and pictures.

Query parameters: days, user_id (optional), limit (default 50, max 100)

Response:

{
  "events": [
    {
      "event_type": "feature_use",
      "path": "/deals",
      "user_id": "abc",
      "user_name": "Alice",
      "user_picture": "https://...",
      "access_level": "executive",
      "feature": "create_deal",
      "tool": "deals",
      "metadata": "{}",
      "duration": 0,
      "timestamp": "2026-03-13T10:30:00Z"
    }
  ]
}

Configuration

The Usage API requires a Cloudflare API token with Analytics Read permission:

• Production: Set via npx wrangler secret put CF_API_TOKEN
• Local dev: Add CF_API_TOKEN=<token> to .dev.vars