knet/docs/tracking-api.md

Tracking API Documentation

The tracking service provides analytics about endpoint usage with time-based filtering.

Authentication

In production, all tracking endpoints require Bearer token authentication:

Authorization: Bearer <your-api-token>

Endpoints

GET /api/tracking/stats

Get endpoint statistics with optional time period filtering.

Query Parameters:

• period (optional): day, week, month, year, all (default: all)

Examples:

# Get all-time stats
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats

# Get last week's stats
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=week

# Get last 30 days
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/stats?period=month

Response:

{
  "stats": [
    {
      "endpoint": "/",
      "method": "GET",
      "hit_count": 245,
      "unique_users": 89,
      "last_access": "2025-08-13T10:30:00Z",
      "first_access": "2025-08-06T14:22:00Z"
    }
  ],
  "period": "week",
  "total_endpoints": 8
}

GET /api/tracking/summary

Get overall tracking summary for a time period.

Query Parameters:

• period (optional): day, week, month, year, all (default: all)

Examples:

# Get today's summary
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=day

# Get yearly summary
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/summary?period=year

Response:

{
  "period": "day",
  "total_hits": 1247,
  "total_endpoints": 12,
  "total_unique_users": 234,
  "oldest_visit": "2025-08-13T00:15:00Z",
  "newest_visit": "2025-08-13T23:45:00Z",
  "tracking_active": true
}

GET /api/tracking/trends

Get visit trends over time with configurable granularity.

Query Parameters:

• granularity (optional): hour, day, week, month (default: day)
• period (optional): 24h, 7d, 30d, 1y (default: 7d)

Examples:

# Hourly trends for last 24 hours
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=hour&period=24h

# Daily trends for last 30 days
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=day&period=30d

# Weekly trends for last year
curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/trends?granularity=week&period=1y

Response:

{
  "trends": [
    {
      "time_bucket": "2025-08-13",
      "hits": 567,
      "unique_users": 123,
      "unique_endpoints": 8
    },
    {
      "time_bucket": "2025-08-12",
      "hits": 445,
      "unique_users": 98,
      "unique_endpoints": 7
    }
  ],
  "granularity": "day",
  "period": "7d"
}

GET /api/tracking/visits

Get recent individual visits with optional filtering.

Query Parameters:

• limit (optional): Number of visits to return (default: 50)

Example:

curl -H "Authorization: Bearer $API_TOKEN" /api/tracking/visits?limit=20

Response:

{
  "visits": [
    {
      "user_hash": "a1b2c3d4e5f6...",
      "endpoint": "/boxes",
      "method": "GET",
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "referer": "https://google.com",
      "timestamp": "2025-08-13T15:30:00Z"
    }
  ],
  "count": 20
}

Benefits of This Approach

1. No Duplication: Single source of truth in user_visits table
2. Flexible Querying: Any time period can be queried on-demand
3. Rich Analytics: Detailed trends and user behavior insights
4. Efficient Storage: Only raw visits stored, stats calculated in real-time
5. Historical Analysis: Can analyze any historical period without pre-aggregation

Performance Considerations

• Indexes are created on timestamp, endpoint, and user_hash for fast queries
• For very high traffic, consider adding materialized views for common time periods
• The SQLite database handles thousands of requests efficiently with proper indexing