Quickstart

Three ways to send events: curl (or any HTTP client), the browser SDK, the Node SDK, or an AI agent via MCP. They all hit the same API.

1. Get an API key

In the dashboard, create a project. You'll get three keys:

Key	Use it from	What it can do
pk_live_…	browsers (origin-restricted)	ingest only
sk_live_…	servers, scripts, anywhere private	ingest only
rk_live_…	servers, MCP clients, dashboards	read only

Add your site's origin to the project's allowlist before using pk_* keys from a browser.

2. Send your first event

curl

curl -X POST https://api.millimetric.ai/v1/track \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "signup",
    "anonymous_id": "u_abc",
    "user_id": "user_42",
    "url": "https://yoursite.com/?utm_source=facebook&utm_medium=cpc",
    "properties": { "plan": "free" }
  }'

Browser — snippet (any HTML page)

<script async src="https://cdn.millimetric.ai/v1/a.js"
        data-key="pk_live_…"></script>
<script>
  // optional: track a custom event
  window.mm?.track("clicked_pricing", { plan: "pro" });
</script>

What you get automatically:

• $pageview on load and every SPA route change

• anonymous_id in localStorage (no cookies)

• Captures utm_*, fbclid, gclid, ttclid, msclkid, li_fat_id, viewport, language, timezone

• Respects DNT / Global Privacy Control

• Batches events; flushes on pagehide via sendBeacon

Browser — npm (React / Next / Vue / Svelte)

npm i @millimetric/track

import { init, track, identify, page } from "@millimetric/track";

init({ key: "pk_live_…" });
track("signup", { plan: "free" });
identify(user.id, { email: user.email });

Node / Bun

npm i @millimetric/track-node

import { init, track, flush } from "@millimetric/track-node";

init({ key: "sk_live_…", host: "https://api.millimetric.ai" });
track({ event: "purchase", anonymous_id: req.cookies.aid, user_id: user.id,
        properties: { amount_cents: 4900 } });
// at the end of a serverless handler:
await flush();

AI agent via MCP

Point any MCP-speaking agent at https://api.millimetric.ai/mcp with a Bearer token. Only server-side keys are accepted — pk_* is rejected because it's designed to ship in browser JS. Tools available:

• track_event (requires an sk_* or admin key)

• query_events, get_stats, top_sources (rk_*)

Example tool call:

{ "name": "top_sources",
  "arguments": { "from": "2026-05-01T00:00:00Z", "to": "2026-05-16T00:00:00Z",
                 "breakdown": "source_medium" } }

3. Query your data

# Source/medium breakdown (this is what makes FB social vs paid show up)
curl "https://api.millimetric.ai/v1/sources?from=2026-05-01&to=2026-05-16&breakdown=source_medium" \
  -H "Authorization: Bearer rk_live_…"

# Aggregate stats
curl "https://api.millimetric.ai/v1/stats?metric=count&from=2026-05-01&to=2026-05-16&event=signup&group_by=source,medium&interval=day" \
  -H "Authorization: Bearer rk_live_…"

# Raw events
curl "https://api.millimetric.ai/v1/query?from=2026-05-01&to=2026-05-16&event=signup&limit=100" \
  -H "Authorization: Bearer rk_live_…"

4. Privacy operations

# Forget every event for a user (GDPR delete)
curl -X POST https://api.millimetric.ai/v1/forget \
  -H "Authorization: Bearer sk_live_…" \
  -d '{"user_id":"user_42"}'

# Bind an anonymous id to a user id
curl -X POST https://api.millimetric.ai/v1/identify \
  -H "Authorization: Bearer sk_live_…" \
  -d '{"anonymous_id":"u_abc","user_id":"user_42","traits":{"plan":"pro"}}'

How attribution is classified

Every event runs through a server-side classifier that turns raw utm_*, click IDs, and referrer into a clean (source, medium, confidence) tuple. The rules cascade, first match wins:

1. gclid/msclkid/ttclid/li_fat_id ⇒ network / paid / high.

2. fbclid arriving via l.facebook.com or lm.facebook.com ⇒ facebook / paid / high (Meta's ad-redirect hosts).

3. fbclid + utm_source=facebook|instagram|meta ⇒ facebook|instagram / paid / high.

4. utm_medium=cpc|paid|paid_social|cpm|display|retargeting ⇒ paid / high.

5. fbclid alone, no other context ⇒ facebook / paid / medium (fbclid can leak onto organic shares but the dominant case is ad clicks).

6. Explicit utm_source with no paid signal ⇒ source / utm_medium / high.

7. Referrer ∈ Facebook hosts without fbclid ⇒ facebook / social / medium.

8. Other known social referrers (twitter, linkedin, reddit, tiktok, youtube, pinterest, …) ⇒ source / social / medium.

9. Search engines (google.*, bing, duckduckgo, …) ⇒ source / organic / medium.

10. Email clients / ESPs ⇒ email / email / medium.

11. Same-host referrer ⇒ internal / direct / high.

12. No referrer & no UTM & no click ID ⇒ direct / direct / high.

13. Otherwise ⇒ slug of referrer host / referral / low.

The matching rule's id is stored on every event so you can audit or re-classify later.