Millimetric Track

Send analytics events to Millimetric's API. server-side keys only (sk_live_…). the classifier auto-derives source/medium/campaign from url + referrer + click IDs, so don't try to set those yourself.

intent

use this skill when the user wants to emit a server-side analytics event to millimetric, link an anonymous visitor to a user id, bulk-upload events from a backfill or webhook, or process a gdpr erasure request. the skill wraps millimetric's /v1/track, /v1/identify, /v1/batch, and /v1/forget endpoints. do not use this for reading analytics data (use millimetric-query), connecting an ai agent (use millimetric-mcp-setup), or browser-side instrumentation (drop the <script> snippet instead).

inputs

environment variables:

• MILLIMETRIC_KEY (required): server-side api key, format sk_live_*_*_*. scope: ingest. generate at https://api.millimetric.ai.
• MILLIMETRIC_HOST (optional): api endpoint. defaults to https://api.millimetric.ai. for local dev, set to http://localhost:8787.

external connection:

• millimetric api at $MILLIMETRIC_HOST (https or http). requires outbound https/http on port 443/80.

binaries:

• curl (for shell commands). alternatively, use the node sdk: @millimetric/track-node (npm package).

caller inputs (per request):

• event name (required): 1-128 chars. system events start with $ (e.g. $pageview).
• anonymous_id (optional): uuid for anonymous visitor. server generates one if omitted.
• user_id (optional): stable internal user id. required for /v1/identify and /v1/forget.
• url (optional): landing url with utm params, fbclid, gclid. classifier reads this to derive attribution.
• referrer (optional): http referrer header. classifier reads this.
• properties (optional): free-form json object, capped at 8 kb after stringify.
• timestamp (optional): iso 8601. defaults to server time.
• event_id (optional): idempotency key, 1-128 chars. prevents duplicate ingest on retry.
• session_id (optional): defaults to ${anonymous_id}-${30min_bucket}.
• path (optional): url path only, no query string.

procedure

step 1: validate api key format

• input: $MILLIMETRIC_KEY env var.
• check that key matches regex (sk|pk|rk)_live_[a-z0-9]+_[a-z0-9]+_[a-z0-9]+.
• if format invalid, fail with "malformed api key".
• output: key is well-formed.

step 2: determine operation type

• input: user request (track event, identify user, batch upload, forget user).
• branch: if user asks to log/track/emit/send/record an event, proceed to track. if user asks to link/identify an anonymous id to a user id, proceed to identify. if user asks to bulk-upload/backfill/batch events, proceed to batch. if user asks to delete/forget/erase a user, proceed to forget.
• output: operation type selected.

step 3a (track): emit single event

• input: event name, anonymous_id, user_id (optional), url, referrer, properties, timestamp, event_id.
• validate: event length 1-128 chars. properties object size after stringify must be <= 8 kb.
• construct curl request:

  curl -X POST "$MILLIMETRIC_HOST/v1/track" \
    -H "Authorization: Bearer $MILLIMETRIC_KEY" \
    -H "Content-Type: application/json" \
    -d '{...}'
  

• body includes: event, anonymous_id, user_id, url, referrer, properties, timestamp, event_id, path, session_id (as provided).
• send request.
• output: http response with status and body (expected: 202 with { "ok": true, "event_id": "..." }).

step 3b (identify): link anonymous to user

• input: anonymous_id, user_id, traits (optional).
• validate: both anonymous_id and user_id must be non-empty strings.
• construct curl request:

  curl -X POST "$MILLIMETRIC_HOST/v1/identify" \
    -H "Authorization: Bearer $MILLIMETRIC_KEY" \
    -H "Content-Type: application/json" \
    -d '{"anonymous_id":"...","user_id":"...","traits":{...}}'
  

• send request.
• output: http response with status and body (expected: 202 with { "ok": true }).

step 3c (batch): upload multiple events

• input: array of events (up to 500 per request). each event has: event, anonymous_id, user_id, properties, timestamp, event_id, url, referrer, path, session_id.
• validate: event count <= 500. total request body size <= 256 kb. each event.properties <= 8 kb.
• construct curl request:

  curl -X POST "$MILLIMETRIC_HOST/v1/batch" \
    -H "Authorization: Bearer $MILLIMETRIC_KEY" \
    -H "Content-Type: application/json" \
    -d '{"events":[...]}'
  

• send request.
• output: http response with status and body (expected: 202 with { "ok": true }).

step 3d (forget): erase user data

• input: user_id.
• validate: user_id must be non-empty string. api key must be sk_* (secret key, not public or read-only).
• construct curl request:

  curl -X POST "$MILLIMETRIC_HOST/v1/forget" \
    -H "Authorization: Bearer $MILLIMETRIC_KEY" \
    -H "Content-Type: application/json" \
    -d '{"user_id":"..."}'
  

• send request.
• output: http response with status and body (expected: 202 with { "ok": true }).

step 4: handle response

• input: http status and response body from millimetric.
• if status is 202, extract event_id and confirm success.
• if status is 400, 401, 403, or 429, parse error code and message from response body.
• output: success response or error details.

step 5: retry on failure (optional)

• input: http status, Retry-After header (if present).
• if status is 429 (rate limited), read Retry-After header and wait that many seconds before retrying.
• if status is 5xx or network timeout, retry with exponential backoff (1s, 2s, 4s, 8s, max 3 retries).
• output: final response after retries exhausted or success.

decision points

if using browser-side tracking: skip this skill entirely. instead, instruct the user to drop the millimetric script tag into their html: <script src="https://cdn.millimetric.ai/v1/a.js" data-key="pk_live_..."></script>. never paste pk_* keys into shell or server code.

if operation is track or batch: accept optional fields (url, referrer, properties, timestamp, session_id). if url or referrer is provided, millimetric's classifier will auto-derive source/medium/campaign. do not manually set source, medium, campaign, source_confidence, source_rule_id, country, device_type, browser, os, or ip_hash; the server enriches these.

if operation is identify: both anonymous_id and user_id are required. traits (custom user attributes) are optional. after identifying, all subsequent track calls for that visitor must include the user_id.

if operation is batch: enforce limits: max 500 events per request, max 256 kb total body. if more than 500 events, split into multiple batch requests. if any single event.properties exceeds 8 kb, reject that event before sending.

if operation is forget: only sk_* (secret) keys are allowed. if key is pk_* (public) or rk_* (read-only), return error forget_requires_secret_key. user_id is required.

if api key is missing or malformed: fail immediately with "millimetric api key not set or invalid. set env var MILLIMETRIC_KEY to sk_live_*_*_*".

if millimetric host is unreachable (connection timeout, dns failure, or 5xx): retry with exponential backoff. after 3 retries, fail with "millimetric api unavailable after 3 attempts".

if rate limited (429 response): read the Retry-After header (e.g. "60"). wait that many seconds and retry up to 1 time. if still rate limited, return error with advice: "you are hitting millimetric's rate limits. track events are limited to 50/sec (burst 200). batch is limited to 5/sec (burst 20). reduce event frequency or contact support."

if payload is invalid (400 response): check error code. if invalid_payload, likely cause is missing event name or properties > 8 kb. if payload_too_large, body exceeds 256 kb in batch. return error with hints.

if result set is empty (e.g. no events in batch): still send the request; millimetric will accept an empty batch as valid.

output contract

on success:

• http status 202 accepted.
• response body: json object with { "ok": true, "event_id": "evt_..." } (for track/identify/forget) or { "ok": true } (for batch).
• side effect: event(s) are queued for ingestion into millimetric. they appear in analytics dashboards within 1-5 minutes.

on error:

• http status 400, 401, 403, or 429.
• response body: json object with { "error": "error_code", "message": "human readable message" }.
• no side effect; event not ingested.

edge cases:

• network timeout (no response within 10s): treat as 5xx, retry with backoff.
• malformed response json: treat as 5xx, retry.
• event_id collision (sending same idempotency key twice): second request is a no-op; millimetric deduplicates.
• anonymous_id reused across /v1/identify calls: later identify calls update the same anon visitor's traits. do not assume isolation.
• user_id reused in /v1/forget: all data for that user_id is erased (cannot be undone). confirm with user before calling forget.

outcome signal

the skill worked if:

• http response is 202 accepted.
• response body contains "ok": true.
• (for track) the user sees an event_id in the response, confirming the event was accepted.
• (for identify) the user can now send track events with the same user_id and they will be linked to the identified traits.
• (for batch) all 500 or fewer events were accepted (status 202).
• (for forget) the user_id is marked for deletion; within 24 hours, all associated data is erased from millimetric.

in real-time: log the response body to stdout or to a dashboard. check millimetric's analytics ui (https://api.millimetric.ai) to see events arriving. if no events appear within 5 minutes, check api key validity, network connectivity, and error logs for 400/401/429 responses.

---

node sdk alternative

npm i @millimetric/track-node

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

init({ key: process.env.MILLIMETRIC_KEY!, host: "https://api.millimetric.ai" });

track({
  event: "purchase",
  anonymous_id: req.cookies.aid,
  user_id: user.id,
  properties: { amount_cents: 4900, currency: "usd" }
});

await flush();   // important in serverless handlers

common errors

status	error	fix
400	invalid_payload	event missing or properties > 8 kb.
401	malformed_api_key	key doesn't match (pk|sk|rk)_*_*_*.
401	invalid_api_key	key not found in db. regenerate at https://api.millimetric.ai.
403	origin_not_allowed	using pk_* from non-allowlisted origin. switch to sk_* for server-side.
403	forget_requires_secret_key	/v1/forget called with pk_*. use sk_* only.
429	rate_limited	back off using Retry-After header. track: 50/s burst 200. batch: 5/s burst 20.

key hygiene

• pk_live_… → browser snippet only. never paste into shell, server code, or this skill.
• sk_live_… → server-side ingest. use here.
• rk_live_… → read-only. for millimetric-query skill, not this one.

see also

• query / analytics: millimetric-query
• ai agent / mcp setup: millimetric-mcp-setup
• attribution rules: https://api.millimetric.ai (docs/concepts/attribution.md)

---

credits: original author soybelli (clawhub). enriched for implexa quality standards.