Analytics API Reference

All analytics endpoints require authentication and project access. Pass your API token via the Authorization: Bearer <token> header.

Overview

GET /api/analytics/overview

Returns aggregate metrics for a site over a time range.

Query parameters

Response

{
  "visitors": 1842,
  "pageviews": 5231,
  "avgSessionDuration": 124500,
  "bounceRate": 0.34,
  "range": "24h"
}

Web Vitals

GET /api/analytics/vitals

Returns percentile data for Core Web Vitals, optionally filtered by flag.

Query parameters

Response

{
  "vitals": [
    { "metric": "lcp", "p50": 1200, "p75": 1850, "p95": 3200, "count": 4521 },
    { "metric": "cls", "p50": 0.03, "p75": 0.08, "p95": 0.18, "count": 4521 },
    { "metric": "inp", "p50": 85, "p75": 145, "p95": 320, "count": 3890 },
    { "metric": "ttfb", "p50": 120, "p75": 280, "p95": 650, "count": 4521 },
    { "metric": "fcp", "p50": 900, "p75": 1400, "p95": 2200, "count": 4521 }
  ],
  "timeSeries": [],
  "range": "7d"
}

Caching: Cache-Control: private, max-age=30

Flag Impact

GET /api/analytics/flag-impact

Returns per-variant performance metrics for each active flag.

Query parameters

Response

{
  "impact": [
    {
      "flagKey": "new-checkout",
      "variants": [
        { "variant": "control", "pageviews": 2100, "sessions": 820, "lcpP75": 1900, "avgCls": 0.05 },
        { "variant": "v2", "pageviews": 2050, "sessions": 810, "lcpP75": 1650, "avgCls": 0.04 }
      ]
    }
  ],
  "range": "24h"
}

Caching: Cache-Control: private, max-age=30

Admin Funnel

GET /api/analytics/admin-funnel

Returns first-party Flaggr console activation metrics for a project.

Query parameters

Response

{
  "projectId": "proj_abc123",
  "range": "7d",
  "funnel": {
    "steps": [
      { "event": "screen_viewed", "users": 120, "conversionRate": 1, "dropOffRate": 0 },
      { "event": "flag_viewed", "users": 86, "conversionRate": 0.72, "dropOffRate": 0.28 },
      { "event": "activation", "users": 51, "conversionRate": 0.43, "dropOffRate": 0.41 }
    ]
  },
  "experimentCycleTime": {
    "sampleSize": 8,
    "medianHours": 18.5
  }
}

Caching: Cache-Control: private, max-age=30

Adoption Cohorts

GET /api/analytics/adoption-cohorts

Returns weekly create-to-view adoption cohorts for a project.

Query parameters

Response

{
  "projectId": "proj_abc123",
  "range": "30d",
  "cohorts": [
    {
      "week": "2026-05-11T00:00:00.000Z",
      "createdProjects": 12,
      "adoptedProjects": 9,
      "adoptionRate": 0.75
    }
  ]
}

Caching: Cache-Control: private, max-age=60

Events

GET /api/analytics/events

Returns the most recent raw events.

Query parameters

Response

{
  "events": [
    {
      "id": 12345,
      "type": "webvital",
      "url": "/checkout",
      "timestamp": "2026-03-20T10:30:00.000Z",
      "country": "US",
      "browser": "Chrome",
      "os": "macOS",
      "device": "desktop",
      "flags": { "new-checkout": "v2" },
      "data": { "metric": "lcp", "value": 1650, "rating": "good" }
    }
  ]
}

Caching: Cache-Control: private, max-age=5

Flag Variant Statistics

GET /api/analytics/flags/{key}/variants

Returns detailed per-variant analytics for a specific flag, including evaluation counts, conversion rates, and latency.

Query parameters

Response

{
  "flagKey": "new-checkout",
  "environment": "production",
  "period": "7d",
  "variants": [
    {
      "variant": "control",
      "evaluations": 12500,
      "conversions": 625,
      "conversionRate": 0.05,
      "avgEventValue": 42.50,
      "latencyP50": 3.2,
      "latencyP99": 18.5
    }
  ],
  "totalEvaluations": 24800,
  "totalConversions": 1363,
  "overallConversionRate": 0.055
}

Caching: Cache-Control: private, max-age=30

Funnel Analysis

GET /api/analytics/funnel

Analyze multi-step conversion funnels segmented by flag variant.

Query parameters

Response

{
  "projectId": "proj_abc123",
  "flagKey": "new-checkout",
  "steps": ["page_view", "add_to_cart", "checkout", "purchase"],
  "funnelSteps": [
    {
      "step": "page_view",
      "stepIndex": 0,
      "totalUsers": 5000,
      "byVariant": { "control": 2500, "v2": 2500 },
      "dropOffRate": 0
    },
    {
      "step": "purchase",
      "stepIndex": 3,
      "totalUsers": 600,
      "byVariant": { "control": 250, "v2": 350 },
      "dropOffRate": 0.25
    }
  ],
  "variants": ["control", "v2"],
  "overallConversionRate": 0.12
}

Caching: Cache-Control: private, max-age=30

Export

POST /api/analytics/export

Export evaluation metrics and outcome events to a webhook endpoint.

Request body

{
  "projectId": "proj_abc123",
  "destination": "webhook",
  "webhookUrl": "https://example.com/analytics-hook",
  "signingSecret": "whsec_...",
  "dataTypes": ["evaluations", "outcomes"],
  "period": "24h"
}

Response

{
  "ok": true,
  "exported": {
    "evaluations": 24800,
    "outcomes": 1363
  }
}

Ingestion Endpoint

POST https://ingest.flaggr.dev/e

This is the Cloudflare Worker endpoint that receives events from the browser analytics script. You generally don't call this directly — the script handles it.

Request

• Content-Type: application/json
• Body: JSON array of event objects (max 100 items, max 100KB)
• Optional header: X-Write-Token for write-protected projects

Response

{
  "accepted": 18,
  "rejected": 2
}

Status: 202 Accepted

Admin Event Ingestion

POST /ingest/admin-events

This endpoint receives first-party console analytics from the Flaggr admin web app. You generally do not call it directly; the console instrumentation batches events automatically.

Request

• Content-Type: application/json
• Body: JSON array of admin event objects (max 100 events per batch)
• Allowed site IDs: flaggr_admin_prod, flaggr_admin_preview, flaggr_admin_dev, or the configured NEXT_PUBLIC_FLAGGR_ANALYTICS_SITE_ID / FLAGGR_ANALYTICS_SITE_ID
• Timestamp window: occurredAt must be no more than 2 hours old and no more than 60 seconds in the future

[
  {
    "source": "flaggr-admin",
    "siteId": "flaggr_admin_preview",
    "sessionId": "session_abc",
    "installId": "install_abc",
    "userId": "user_123",
    "event": "flag_viewed",
    "occurredAt": "2026-05-17T02:30:00.000Z",
    "appVersion": "admin-web",
    "buildNumber": "development",
    "appVariant": "development",
    "platform": "web",
    "apiOrigin": "http://127.0.0.1:3000",
    "properties": {
      "project_id": "proj_abc123",
      "project_slug": "acme",
      "flag_key": "checkout-flow"
    }
  }
]

Response

{
  "accepted": 1,
  "rejected": 0,
  "siteId": "flaggr_admin_preview"
}

Status: 202 Accepted

Feature Flag Evaluation Analytics & Post-Toggle Safety

In addition to browser analytics, Flaggr provides high-precision server-side evaluation analytics and automated post-toggle safety diagnostics.

Post-Toggle Safety & Drift Analysis

GET /api/flags/{key}/toggle-impact

Calculates pre-change vs post-change metrics around the most recent flag toggle event, classifying the transition as healthy, warning, degraded, or insufficient_data.

Query Parameters

Response Fields

Flag Evaluation Metrics & Time Series

GET /api/flags/{key}/metrics

Returns total volume, realtime rates (evals/sec, evals/min), latency percentiles (P50, P95, P99), reason breakdown (TARGETING_MATCH, DEFAULT_VALUE, ERROR), value distribution, time series buckets, and toggle impact.

Query Parameters

Project Evaluation Heatmap

GET /api/projects/{id}/evaluation-heatmap

Returns an evaluation density heatmap across all services and feature flags in a project, highlighting zero-traffic flags and hotspot workloads.

Query Parameters

Project Aggregated Health

GET /api/projects/{id}/health

Returns platform-level aggregated health score (0–100), per-service status, top degradation issues, and total evaluation traffic.

Accessing Analytics via Model Context Protocol (MCP)

All analytics endpoints are directly callable by AI coding assistants and autonomous agents via @flaggr/mcp-server:

Agents can also read the dynamic MCP resource: flaggr://flag/{key}/toggle-impact

And trigger the safety prompt: verify_toggle_safety

Rate Limits

The ingestion endpoint enforces 100 requests per minute per IP via Cloudflare rate limiting rules. API query endpoints follow the standard Flaggr rate limits documented in Rate Limiting.

Next Steps

• Flag Health Guide — Automated health scoring and drift detection
• MCP Server Guide — Using Flaggr with Claude, Cursor, and AI agents
• Browser Analytics — Install and configure the script
• Analytics Dashboard — Visual guide to the dashboard
• Admin Analytics — Console activation funnels and adoption cohorts
• Analytics & A/B Testing — Measure experiments with analytics