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.

AI-related requests are HTTP requests classified into assistant, training-crawler, coding-agent, or AI-referral categories. They are not unique people or sessions.

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

Observed HTTP request totals, the human/AI-related/other-automated split, and the four canonical AI-related request categories.

{
  "total_visits": 42557,
  "human_clicks": 38771,
  "ai_visits": 3786,
  "ai_assistant_requests": 1600,
  "ai_training_requests": 1400,
  "ai_coding_agent_requests": 386,
  "ai_referral_requests": 400,
  "other_visits": 0,
  "ai_percentage": 8.9
}

ai_assistant_requests, ai_training_requests, ai_coding_agent_requests, and ai_referral_requests expose the category counts. Together they form AI-related Requests. ai_visits is retained as the compatibility total for those four AI-related categories, and ai_percentage is the compatibility AI-related Request Share of total observed requests. These are request counts, not unique people, sessions, citations, or confirmed referral outcomes.

GET /api/analytics/weekly-trend

Week-by-week request breakdown with canonical AI-related category fields and per-platform detail.

{
  "weekly": [
    {
      "week": "2026-03-17",
      "total_visits": 8631,
      "human_visits": 7645,
      "ai_visits": 986,
      "ai_assistant_requests": 400,
      "ai_training_requests": 350,
      "ai_coding_agent_requests": 136,
      "ai_referral_requests": 100,
      "other_visits": 0,
      "ai_pct": 11.4
    }
  ],
  "byPlatform": [
    { "week": "2026-03-17", "ai_source": "chatgpt", "visits": 174 }
  ]
}

The weekly ai_visits and ai_pct fields retain the compatibility AI-related request total and share. Use the four category fields when the distinction between assistant, training-crawler, coding-agent, and AI-referral requests matters.

GET /api/analytics/time-series

Daily time series of observed requests (total, human, AI-related, mobile, desktop).

AI Sources

GET /api/analytics/ai-sources

Breakdown of AI-related requests by platform with request counts and percentages.

Observed assistant-only request mix across AI platforms, scoped to bot_category = 'ai_assistant' and excluding malicious paths. It excludes model-training crawlers, ordinary search crawlers, and unknown automation. Each row includes request count, share, distinct non-empty requested paths as pages_accessed, and distinct available privacy-safe visitor hashes as unique_visitors. The unique_visitors compatibility field counts hashes, not verified unique people or sessions; zero 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.