Insights API

The Insights API is a small set of read-only REST endpoints over the same data that powers your dashboard: usage overview, subscriber health, funnels, paths, person cohorts, and per-user detail. Build your own dashboard, feed a data warehouse, or script a report - no write path exists here, so there is nothing an integration can break.

Auth

Every endpoint requires a secret key - sk_live_ or sk_test_ - passed as a bearer token. Public pk_* keys are rejected with requires_secret_key (403); this is aggregate business data, not something safe to ship in a browser bundle.

curl https://www.vevee.org/api/v1/analytics/overview?window=30 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

The key prefix decides the universe: an sk_live_ key reads live data, an sk_test_ key reads sandbox (test_*) data. There is no separate mode parameter to pass - the same rule as every other Vevee endpoint.

Response envelope

Every response, success or failure, follows the same shape as the rest of the API:

{ "ok": true, "data": { /* endpoint-specific */ } }

{ "ok": false, "error": { "code": "not_found", "message": "User not found." } }

Relationship to the MCP server

The Insights MCP server exposes this exact same data as tools an AI agent can call, over the same secret key and the same { ok, data } results underneath. Same data, same privacy rules, same live/test split - the only difference is the transport: reach for the Insights APIwhen you're writing code (a dashboard, a script, a cron job), and reach for the MCP server when you want an agent to answer questions in plain English.

Privacy contract

These endpoints obey the exact same privacy gates as the dashboard - there is no separate, looser code path for API consumers.

• End users who opted out of AI personalization (or opted out entirely) and persons pending deletion are excluded from every person-level endpoint - persons, users, and events, plus the single-user and single-event detail lookups. A request for an excluded user or event id returns not_found, identical to a request for an id that never existed.
• Aggregates include everyone. Overview and subscriber stats count opted-out and pending-deletion end users like anyone else - only per-person detail is withheld.
• Prompt and response text is exposed by the events endpoints only when prompt logging is enabled for the app, and never for opted-out or pending-deletion end users - their events are excluded from both endpoints entirely. No other endpoint reads event_logs at all.

Endpoints