API Reference

REST API for stats, bot management, campaigns, experiments, and performance metrics.

Authentication

All API endpoints (except /api/health) require one of:

• Bearer token: Authorization: Bearer <ECHELON_SECRET>
• Session cookie: echelon_session from password login

Cookie-authenticated POST/PATCH/DELETE requests require CSRF validation (Origin or Referer header must match the server host).

Public Endpoints

Returns the tracker script with embedded WASM proof-of-work challenge. No auth required.

Pageview beacon. Returns a 1x1 transparent GIF. Query params include path, site ID, session ID, PoW token, screen dimensions, and UTM data. No auth required.

Behavioral events endpoint (via sendBeacon). Accepts JSON with event array, site ID, and PoW token. Returns 204 No Content. Max 16 KB body, max 20 events per request. No auth required.

Health check. No auth required.

{ "status": "ok", "service": "Echelon Analytics" }

📦 "Did you know you can bulk ingest historical data via POST /api/ingest? Perfect for migrating from another analytics platform or backfilling data." -🦭

Stats

Overview statistics for a site. Visitors, pageviews, top pages, devices, countries, referrers, daily trends. days defaults to 30 (max 730).

Live dashboard data: active visitors (now), 60-minute trend (per-minute), 24-hour trend (per-hour), recent visitors and recent events. Powers the live dashboard island.

Realtime stats: active visitors, pageviews, and active paths from the last 5 minutes.

Summary across all sites.

Live system vitals: in-memory buffer sizes and 24h aggregates.

{
  "buffers": { "views": 42, "events": 17 },
  "last_24h": {
    "total_views": 1234,
    "human_views": 1100,
    "bot_views": 134,
    "unique_visitors": 890
  }
}

Campaign statistics. Optional id param for detailed breakdown by source, medium, content, and term. days defaults to 30 (max 90).

Campaign-to-event correlation. For each campaign (plus organic traffic as baseline): visitors, event-triggering visitors, event count, event rate, events per visitor, and per-campaign event type breakdown. Use to measure whether campaign visitors adopt features or convert. event_type is optional — when set, only counts that specific event.

Experiment statistics with variant conversion rates and significance testing.

Campaigns

See UTM Campaign Tracking for a complete guide on setting up campaigns, URL format, and how attribution works.

List all UTM campaigns.

[{
  "id": "spring-2026",
  "name": "Spring Launch",
  "utm_campaign": "spring-2026",
  "site_id": "default",
  "status": "active",
  "created_at": "2026-03-01T00:00:00Z"
}]

Create a campaign. Returns 201.

# Request
{
  "id": "spring-2026",
  "name": "Spring Launch",
  "utm_campaign": "spring-2026",
  "site_id": "default"
}

# Response
{ "created": "spring-2026" }

id must be alphanumeric plus ._- (max 128 chars). site_id defaults to "default".

Update campaign status.

{ "status": "active" | "paused" | "archived" }

Delete a campaign. Returns { "deleted": "campaign-id" }.

Experiments

See A/B Experiments for a complete guide on creating experiments, tracking conversions, and understanding statistical significance.

List all A/B experiments with variants.

Create an experiment. Returns 201.

{
  "experiment_id": "checkout-v2",
  "name": "Checkout Redesign",
  "description": "Test new checkout flow",
  "metric_event_type": "purchase",
  "allocation_percent": 100,
  "variants": [
    { "variant_id": "control", "name": "Original", "weight": 50, "is_control": true },
    { "variant_id": "redesign", "name": "New Flow", "weight": 50 }
  ]
}

Max 20 variants. config (optional JSON) max 4096 chars per variant.

Update experiment status. Sets started_at on transition to "active" and ended_at on "completed" or "archived".

{ "status": "draft" | "active" | "paused" | "completed" | "archived" }

Bot Management

List suspicious visitors. Returns aggregated metrics per visitor: max bot score, pageview count, devices, countries, exclusion status. limit max 200.

List all manually excluded visitors with pageview counts.

Exclude a visitor from rollups. Returns 201.

{ "visitor_id": "abc123", "label": "Known bot" }

Remove a visitor from the exclusion list.

{ "included": "abc123" }

Detailed visitor data: exclusion status, last 100 views, and last 100 events.

Performance Metrics

Query stored performance metrics. All params optional.

Ingest performance metrics (e.g. from CI/CD).

[{
  "category": "build",
  "metric": "bundle_size",
  "value": 142.5,
  "unit": "kb"
}]

Performance trends over time.

Sites

Get site settings (consent CSS).

Update site consent CSS (max 4096 chars).

Data Ingest

Bulk ingest visitor views and events. Max 1 MB body.

Error Responses