Analytics Endpoints

Complete reference for SeeLLM's analytics API endpoints.

Every endpoint in this reference requires Authorization: Bearer <firebase_jwt_or_api_key>. The generated OpenAPI contract provides core response schemas for traffic overview, AI sources, time series, weekly trends, Jobs, and Agent Hooks; the remaining analytics endpoints publish their response envelope and known fields as the current contract.

Analytics requests accept range, start_date, end_date, short_code, target_url, and domain; /analytics/bot-traffic additionally accepts traffic_type. The server uses range (default 30d) unless both custom dates are supplied; target_url takes precedence over short_code. There is no pagination. Each response includes the global rate-limit headers documented on the API overview.

/analytics/domain-breakdown is the exception: it uses target_url to resolve a short code and ignores an explicit short_code query parameter.

Dashboard (Combined)

GET /api/analytics/dashboard

Returns all key metrics in a single request. Recommended for dashboard loading — avoids multiple round trips.

curl "https://api.seellm.link/api/analytics/dashboard?range=30d" \
  -H "Authorization: Bearer sk_live_..."

Returns overview, timeSeries, aiSources, devices, topLinks, and more in one response.

Traffic

GET /api/analytics/traffic-overview

Total visits, human clicks, AI visits, and AI percentage.

{
  "total_visits": 42557,
  "human_clicks": 38771,
  "ai_visits": 3786,
  "ai_percentage": 8.9
}

GET /api/analytics/weekly-trend

Week-by-week breakdown with per-platform AI detail.

{
  "weekly": [
    { "week": "2026-03-17", "total_visits": 8631, "human_visits": 7645, "ai_visits": 986, "ai_pct": 11.4 }
  ],
  "byPlatform": [
    { "week": "2026-03-17", "ai_source": "chatgpt", "visits": 174 }
  ]
}

GET /api/analytics/time-series

Daily time series of visits (total, human, AI, mobile, desktop).

AI Sources

GET /api/analytics/ai-sources

Breakdown of traffic by AI platform with visit counts and percentages.

Observed request mix across AI platforms, scoped to traffic_type = "Search AI" and excluding malicious paths. Each row includes request count, share, distinct non-empty requested paths as pages_accessed, and distinct available privacy-safe visitor hashes as unique_visitors. A zero visitor count means the identifier was unavailable. Page access does not prove that an AI answer cited the page.

GET /api/analytics/developer-tools

Traffic from developer-focused AI tools (Cursor, GitHub Copilot, etc.).

GET /api/analytics/dev-tools-adoption

Developer tools adoption metrics.

GET /api/analytics/ai-confidence

AI detection confidence distribution.

Content & Pages

GET /api/analytics/top-links

GET /api/analytics/ai-to-human-conversion

AI-to-human conversion funnel data.

GET /api/analytics/traffic-value-breakdown

Estimated traffic value broken down by type.

Devices & Geography

GET /api/analytics/devices

Device type breakdown (desktop, mobile, tablet, bot).

GET /api/analytics/operating-systems

OS distribution across visits.

GET /api/analytics/browsers

Browser distribution.

GET /api/analytics/device-by-ai-source

Cross-tabulation of device types by AI source.

GET /api/analytics/geographic

Geographic distribution of visits.

Time Patterns

GET /api/analytics/hourly-activity

Hourly distribution of visits.

GET /api/analytics/daily-activity

Day-of-week distribution.

GET /api/analytics/peak-times

Peak traffic times analysis.

GET /api/analytics/weekend-vs-weekday

Weekend vs weekday traffic comparison.

Campaigns & Referrals

GET /api/analytics/utm-campaigns

UTM campaign performance.

GET /api/analytics/referrers

Referrer breakdown.

Domain & Bot Analysis

GET /api/analytics/domain-breakdown

Traffic breakdown by domain (for multi-domain setups).

GET /api/analytics/bot-traffic

Bot traffic list with detailed classification.

Utility

GET /api/analytics/filter-values

Available filter values for the current organization.

GET /api/analytics/cache-stats

Server-side cache performance metrics.

Errors and Retries

Authentication failures return HTTP 401 with an { "error": "..." } body. The dashboard may return HTTP 500 with error and message if its analytics fetch fails. On HTTP 429, wait for Retry-After; no endpoint-specific timeout or retry guarantee is published.