---
title: Analytics Endpoints
description: Complete reference for SeeLLM's analytics API endpoints.
audience: [human, agent]
type: reference
version: v1
stability: stable
lastVerified: "2026-08-01"
prerequisites: [/docs/api/authentication/]
related: [/docs/api/, /docs/api/jobs/, /docs/concepts/ai-traffic-types/]
artifacts: [{ label: OpenAPI contract, url: /docs/api/openapi.json }]
---

Every endpoint in this reference requires `Authorization: Bearer <firebase_jwt_or_api_key>`. The generated [OpenAPI contract](/docs/api/openapi.json) 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](/docs/api/).

`/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.

```bash
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.

```json
{
  "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.

```json
{
  "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.

### GET /api/analytics/ai-platform-market-share

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

Top performing links by visit count.

### 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.