Stats API

Everything the dashboard shows is available as JSON, at https://millimetry.app/api/v1. Create a read-only token under your organization’s settings → API tokens (admins and owners), then:

curl -H "Authorization: Bearer mt_…" \
  "https://millimetry.app/api/v1/apps/42/overview?from=2026-09-01&to=2026-09-30"

Requests carry a read-only org token (Authorization: Bearer mt_…) or the dashboard’s session cookie. Common query parameters for stats endpoints:

from, to: UTC dates, inclusive.
debug=true: debug data instead of production data.
filter=dimension:value: repeatable, for example filter=country:CA&filter=app_version:1.5.0.
compare=previous: adds the previous period of the same length.

Answers are cached for 30 seconds. Busy periods answer 503 with Retry-After. A query too heavy for its time or memory budget answers 422: narrow the dates or the filters.

The machine-readable document is at /api/v1/openapi.json.

Auth

Sign-in links, sessions.

POST `/auth/logout`

Ends this session.

204

POST `/auth/magic-link`

Sends a sign-in link.

Body: LinkRequest

202 If the address can sign in, a link is on its way
400
429
503

POST `/auth/verify`

Uses a sign-in link: starts a session (the cookie) and returns who signed in. Needs `X-Requested-With`, which a cross-site form cannot send. 404 when the link is unknown, used or expired.

Body: VerifyRequest

200 LinkInfo Signed in; the session cookie is set
403
404

GET `/me`

Who is signed in, and their orgs and roles.

200 Me
401

GET `/me/sessions`

The signed-in person's active sessions.

200 SessionInfo[]

DELETE `/me/sessions/{id}`

Signs out one session (another device).

Parameter	In	Type	Description
`id`	path	string	The session id from /me/sessions

204
404

Apps

Apps, web sites and their keys.

GET `/apps`

The apps the caller may see, across their orgs.

200 AppView[]

POST `/apps`

Creates an app or web site with its first key.

Body: NewApp

201 CreatedApp
400
403
404

GET `/apps/{id}`

One app.

Parameter	In	Type	Description
`id`	path	integer (int32)

200 AppView
404

PATCH `/apps/{id}`

Renames an app, replaces a site's origins, or pauses and resumes ingest.

Parameter	In	Type	Description
`id`	path	integer (int32)

Body: AppChange

200 AppView
400
403
404

DELETE `/apps/{id}`

Deletes an app. Its keys stop at once; its data is purged after a 7-day undo window (§15.6).

Parameter	In	Type	Description
`id`	path	integer (int32)

204
403
404

POST `/apps/{id}/export`

Exports every event of the app to a file; poll `GET /jobs/{id}` for the download link (valid 7 days). Admins and owners: an export holds everything the app ever sent.

Parameter	In	Type	Description
`id`	path	integer (int64)

Body: ExportRequest

202 JobStarted
403
404
429

POST `/apps/{id}/forwarding-secret`

Issues a new forwarding secret for a proxied web install (§12.2).

Parameter	In	Type	Description
`id`	path	integer (int32)

201 ForwardingSecret
400
403
404

GET `/apps/{id}/funnels`

The app's saved funnels.

Parameter	In	Type	Description
`id`	path	integer (int32)

200 FunnelView[]
404

POST `/apps/{id}/funnels`

Saves a funnel for everyone in the org to reuse.

Parameter	In	Type	Description
`id`	path	integer (int32)

Body: NewSavedFunnel

201 FunnelView
400
403
404

DELETE `/apps/{id}/funnels/{funnel_id}`

Deletes a saved funnel.

Parameter	In	Type	Description
`id`	path	integer (int32)
`funnel_id`	path	integer (int64)

204
403
404

GET `/apps/{id}/keys`

The app's keys, active and revoked.

Parameter	In	Type	Description
`id`	path	integer (int32)

200 KeyView[]
404

POST `/apps/{id}/keys`

Adds a key. Rotation is an overlap: add, ship it, revoke the old one later.

Parameter	In	Type	Description
`id`	path	integer (int32)

201 NewKey
403
404

DELETE `/apps/{id}/keys/{key}`

Revokes a key. Ingest stops accepting it within a minute (its key cache).

Parameter	In	Type	Description
`id`	path	integer (int32)
`key`	path	string

204
403
404

GET `/jobs/{id}`

A job the caller's org started (exports).

Parameter	In	Type	Description
`id`	path	integer (int64)

200 JobView
404

Orgs

Orgs, members and API tokens.

GET `/invitations`

What an invitation link is for, before signing in to accept it. 404 when used or expired.

Parameter	In	Type	Description
`token`	query	string

200 InvitationInfo
404

POST `/invitations/accept`

Joins the org. The signed-in address must be the invited one; otherwise, and when the link is used or expired, 404.

Body: AcceptInvitation

200 Joined
404

POST `/orgs`

Creates an org with the caller as its owner, on the free plan.

Body: NewOrg

201 OrgCreated
400

PATCH `/orgs/{id}`

Renames the org.

Parameter	In	Type	Description
`id`	path	integer (int64)

Body: OrgChange

204
400
403
404

DELETE `/orgs/{id}`

Deletes the org: every app stops at once and all its data is purged within minutes (§15.6). Owners only, and the body must repeat the org's name.

Parameter	In	Type	Description
`id`	path	integer (int64)

Body: DeleteOrg

204
400
403
404

GET `/orgs/{id}/invitations`

Pending invitations.

Parameter	In	Type	Description
`id`	path	integer (int64)

200 InvitationView[]
403
404

POST `/orgs/{id}/invitations`

Invites someone by email. Inviting the same address again replaces the earlier invitation.

Parameter	In	Type	Description
`id`	path	integer (int64)

Body: NewInvitation

201 InvitationView
400
403
404
429

DELETE `/orgs/{id}/invitations/{invitation_id}`

Withdraws a pending invitation; its link stops working.

Parameter	In	Type	Description
`id`	path	integer (int64)
`invitation_id`	path	string

204
403
404

GET `/orgs/{id}/members`

The org's members and roles. Invitations come with Milestone B (§20 phase 7).

Parameter	In	Type	Description
`id`	path	integer (int64)

200 Member[]
404

PATCH `/orgs/{id}/members/{user_id}`

Changes a member's role. Admins change admins, members and viewers; owners also owners.

Parameter	In	Type	Description
`id`	path	integer (int64)
`user_id`	path	integer (int64)

Body: RoleChange

204
400
403
404

DELETE `/orgs/{id}/members/{user_id}`

Removes a member; any member may remove themselves (leave). The last owner cannot go.

Parameter	In	Type	Description
`id`	path	integer (int64)
`user_id`	path	integer (int64)

204
400
403
404

GET `/orgs/{id}/tokens`

The org's API tokens (never the tokens themselves).

Parameter	In	Type	Description
`id`	path	integer (int64)

200 TokenView[]
403
404

POST `/orgs/{id}/tokens`

Creates a read-only API token for the org.

Parameter	In	Type	Description
`id`	path	integer (int64)

Body: NewToken

201 CreatedToken
400
403
404

DELETE `/orgs/{id}/tokens/{token_id}`

Revokes an API token at once.

Parameter	In	Type	Description
`id`	path	integer (int64)
`token_id`	path	integer (int64)

204
403
404

Stats

Dashboard queries.

GET `/apps/{id}/breakdown`

Top values of one dimension by events, sessions or users (§16).

Parameter	In	Type
`id`	path	integer (int32)
`dimension`	query	string
`metric` (optional)	query	string
`limit` (optional)	query	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string
`filter` (optional)	query	string[]

200 Breakdown
400
404

GET `/apps/{id}/events`

The app's events by count, each with a daily series for a sparkline (§14.3).

Parameter	In	Type
`id`	path	integer (int32)
`limit` (optional)	query	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string
`filter` (optional)	query	string[]

200 EventsList
400
404

GET `/apps/{id}/events/{name}`

One event: its trend, its text properties' top values, its number properties' statistics, and optionally one number property by a dimension (revenue by version, §13).

Parameter	In	Type
`id`	path	integer (int32)
`name`	path	string
`property` (optional)	query	string
`by` (optional)	query	string
`from` (optional)	query	string
`to` (optional)	query	string
`filter` (optional)	query	string[]

200 EventDetail
400
404

POST `/apps/{id}/funnel`

Ordered steps within a session and a time window (§13 funnel), optionally per dimension value.

Parameter	In	Type
`id`	path	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string
`filter` (optional)	query	string[]

Body: FunnelRequest

200 Funnel
400
404

GET `/apps/{id}/heatmap`

Sessions by weekday and hour (§13).

Parameter	In	Type
`id`	path	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string
`filter` (optional)	query	string[]

200 Heatmap
404

GET `/apps/{id}/live`

Sessions active in the last 5 minutes (§14.3). Never cached.

Parameter	In	Type	Description
`id`	path	integer (int32)
`debug` (optional)	query	boolean

200 Live
404

GET `/apps/{id}/overview`

KPIs and the daily series, from `daily_totals` when unfiltered and raw `events` when filtered.

Parameter	In	Type	Description
`id`	path	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string
`debug` (optional)	query	boolean
`filter` (optional)	query	string[]	dimension:value, repeatable
`compare` (optional)	query	string

200 Overview
400
404

POST `/apps/{id}/paths`

What happens next after an event, within a session (§13).

Parameter	In	Type
`id`	path	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string
`filter` (optional)	query	string[]

Body: PathsRequest

200 Paths
400
404

GET `/apps/{id}/sessions`

Recent sessions and the window's session statistics. No user identity exists to show (§14.3).

Parameter	In	Type	Description
`id`	path	integer (int32)
`limit` (optional)	query	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string
`filter` (optional)	query	string[]	platform, country, os_name or app_version only

200 Sessions
400
404

GET `/apps/{id}/sessions/{session_id}`

One session's events in order.

Parameter	In	Type
`id`	path	integer (int32)
`session_id`	path	string
`debug` (optional)	query	boolean

200 TimelineEvent[]
400
404

GET `/apps/{id}/usage`

Ingest health and the org's quota (§16).

Parameter	In	Type
`id`	path	integer (int32)
`from` (optional)	query	string
`to` (optional)	query	string

200 Usage
404

Billing

Plans, usage and Stripe billing.

GET `/orgs/{id}/billing`

The org's plan, usage and the plans on offer.

Parameter	In	Type	Description
`id`	path	integer (int64)

200 BillingView
404

POST `/orgs/{id}/billing/checkout`

Starts a subscription: a Stripe Checkout Session for the plan's Price. The plan changes only when Stripe's webhook confirms it. An org that already pays changes plan in the Portal.

Parameter	In	Type	Description
`id`	path	integer (int64)

Body: CheckoutRequest

200 Redirect
400
403
503

POST `/orgs/{id}/billing/portal`

Opens the Stripe Customer Portal: change plan, update the card, invoices, cancel.

Parameter	In	Type	Description
`id`	path	integer (int64)

200 Redirect
400
403
503

Schemas

AcceptInvitation

Field	Type	Description
`token`	string

AppChange

Field	Type	Description
`name` (optional)	string, nullable
`origins` (optional)	string[]
`paused` (optional)	boolean, nullable	A paused app's events are dropped and counted (§15.1).

AppView

Field	Type	Description
`created_at`	string
`has_forwarding_secret`	boolean
`id`	integer (int32)
`kind`	string	`app` (SDK batches) or `web` (the tracker).
`name`	string
`org_id`	integer (int64)
`origins`	string[]	Web only: origins allowed to send events.
`paused`	boolean

BillingView

Field	Type	Description
`billing_enabled`	boolean	Whether Checkout and the Portal are available on this server.
`cancel_at` (optional)	string, nullable	When the subscription ends instead of renewing (cancelled at period end); `null` while it renews.
`effective_events_per_month`	integer (int64)	The limit in force: the free plan's once a past-due grace period has ended.
`events_per_month`	integer (int64)	The plan's monthly events.
`grace_until` (optional)	string, nullable
`hard_limit_percent`	integer (int64)	Events are accepted up to this share of the limit, then dropped (§15.4).
`has_billing_account`	boolean	Whether the org has a Stripe customer, so the Portal can open.
`period_end` (optional)	string, nullable
`plan`	string
`plans`	PlanView[]
`status`	string	`none`, `active`, `past_due` or `canceled`.
`used_this_month`	integer (int64)

Breakdown

Field	Type	Description
`dimension`	string
`metric`	string
`rows`	Row2[]
`sampled`	boolean
`source`	string

CheckoutRequest

Field	Type	Description
`plan`	string	The plan to subscribe to, e.g. `pro_1m`.

CreatedApp

Field	Type	Description
`app`	AppView
`key`	string	The first public key (`ak_…` or `wk_…`).

CreatedToken

object

DayPoint

Field	Type	Description
`day`	string
`events`	integer (int64)
`sessions`	integer (int64)
`users`	integer (int64)

DeleteOrg

Field	Type	Description
`confirm`	string	The org's name, typed back: deleting is irreversible.

EventDetail

Field	Type	Description
`name`	string
`number_properties`	NumberProperty[]
`property_by` (optional)	PropertyGroup[]	With `property` and `by`: the number property per value of the dimension.
`sampled`	boolean
`series`	DayPoint[]
`string_properties`	StringProperty[]

EventSummary

Field	Type	Description
`events`	integer (int64)
`name`	string
`series`	integer (int64)[]	Events per day over the window, oldest first, one entry per day (zeros included).
`users`	integer (int64)

EventsList

Field	Type	Description
`events`	EventSummary[]
`sampled`	boolean

ExportFormat

"parquet" | "csv"

ExportRequest

Field	Type	Description
`format` (optional)	ExportFormat	`parquet` (default) or `csv`.

ForwardingSecret

Field	Type	Description
`secret`	string	Shown once; the previous secret stops working.

Funnel

Field	Type	Description
`groups`	FunnelGroup[]	One group without a breakdown; with one, the biggest groups by first-step sessions.
`more_groups`	boolean	Whether groups beyond the first 20 were left out.
`sampled`	boolean

FunnelGroup

Field	Type	Description
`group`	string	The breakdown value, or empty without a breakdown.
`steps`	FunnelStep[]

FunnelRequest

Field	Type	Description
`breakdown` (optional)	string, nullable
`steps`	string[]
`window_seconds` (optional)	integer (int32)

FunnelStep

Field	Type	Description
`conversion`	number (double)	Share of the first step's sessions.
`name`	string
`sessions`	integer (int64)	Sessions that reached this step.
`step_conversion`	number (double)	Share of the previous step's sessions.

FunnelView

Field	Type	Description
`breakdown` (optional)	string, nullable
`created_at`	string
`id`	integer (int64)
`name`	string
`steps`	string[]
`window_seconds`	integer (int32)

HeatCell

Sessions active in one weekday-hour: a session spanning two hours counts in both.

Field	Type	Description
`hour`	integer (int32)	0–23, UTC.
`sessions`	integer (int64)
`weekday`	integer (int32)	1 = Monday … 7 = Sunday.

Heatmap

Field	Type	Description
`cells`	HeatCell[]
`sampled`	boolean

InvitationInfo

Field	Type	Description
`email`	string
`org_name`	string
`role`	string

InvitationView

Field	Type	Description
`email`	string
`expires_at`	string
`id`	string
`role`	string

JobStarted

Field	Type	Description
`job_id`	integer (int64)

JobView

Field	Type	Description
`created_at`	string
`error` (optional)	string, nullable
`id`	integer (int64)
`kind`	string
`result` (optional)	object, nullable
`state`	string	`pending`, `running`, `done` or `failed`.

Joined

Field	Type	Description
`org_id`	integer (int64)

KeyView

Field	Type	Description
`created_at`	string
`key`	string
`revoked_at` (optional)	string, nullable

LinkInfo

Field	Type	Description
`email`	string	The address the link signs in as.

LinkRequest

Field	Type	Description
`email`	string

Live

Field	Type	Description
`events`	integer (int64)
`minutes`	integer (int32)
`sessions`	integer (int64)

Me

Field	Type	Description
`orgs`	object[]
`user`	object

Member

Field	Type	Description
`email`	string
`name` (optional)	string, nullable
`role`	string	`owner`, `admin`, `member` or `viewer`.
`user_id`	integer (int64)

NewApp

Field	Type	Description
`kind`	string	`app` or `web`.
`name`	string
`org_id`	integer (int64)
`origins` (optional)	string[]

NewInvitation

Field	Type	Description
`email`	string
`role`	string	`admin`, `member` or `viewer`; `owner` only from an owner.

NewKey

Field	Type	Description
`key`	string

NewOrg

Field	Type	Description
`name`	string

NewSavedFunnel

Field	Type	Description
`breakdown` (optional)	string, nullable
`name`	string
`steps`	string[]
`window_seconds` (optional)	integer (int32)

NewToken

Field	Type	Description
`name`	string

NumberProperty

Field	Type	Description
`count`	integer (int64)
`key`	string
`mean`	number (double)
`median`	number (double)
`p95`	number (double)
`sum`	number (double)

OrgChange

Field	Type	Description
`name`	string

OrgCreated

Field	Type	Description
`id`	integer (int64)

Overview

Field	Type	Description
`current`	Period
`previous` (optional)	Period \| null
`sampled`	boolean
`source`	string	`daily_totals` (rollup) or `events` (raw, when filtered).

Paths

Field	Type	Description
`after`	string
`next`	Row2[]
`sampled`	boolean

PathsRequest

Field	Type	Description
`after`	string

Period

Field	Type	Description
`from`	string
`series`	DayPoint[]
`to`	string
`totals`	Totals

PlanView

Field	Type	Description
`events_per_month`	integer (int64)
`id`	string
`price_usd_month`	integer (int32)
`purchasable`	boolean	Whether it can be bought now (its Stripe Price is configured).

PropertyGroup

Field	Type	Description
`count`	integer (int64)
`median`	number (double)
`sum`	number (double)
`value`	string

Redirect

Field	Type	Description
`url`	string	Stripe's page; the browser goes there.

RoleChange

Field	Type	Description
`role`	string	`owner`, `admin`, `member` or `viewer`.

Row2

Field	Type	Description
`count`	integer (int64)
`value`	string

SessionInfo

Field	Type	Description
`created_at`	string
`current`	boolean
`expires_at`	string
`id`	string

SessionItem

Field	Type	Description
`app_version`	string
`country`	string
`duration_seconds`	integer (int64)
`ended`	string
`entry`	string	First page (web) or `screen` property (apps).
`events`	integer (int64)
`exit`	string
`id`	string
`pageviews`	integer (int64)
`platform`	string
`referrer_source`	string
`started`	string

SessionSummary

Field	Type	Description
`bounce_rate`	number (double)
`events_per_session`	number (double)
`median_seconds`	number (double)
`sessions`	integer (int64)

Sessions

Field	Type	Description
`sessions`	SessionItem[]
`summary`	SessionSummary

StringProperty

Field	Type	Description
`key`	string
`values`	Row2[]

TimelineEvent

Field	Type	Description
`name`	string
`pathname`	string
`properties`	object
`screen`	string
`ts`	string

TokenView

Field	Type	Description
`created_at`	string
`id`	integer (int64)
`name`	string

Totals

Field	Type	Description
`bounce_rate`	number (double)	Sessions with at most one page view and one event (web).
`events`	integer (int64)
`events_per_session`	number (double)
`median_session_seconds`	number (double)
`pageviews`	integer (int64)
`sessions`	integer (int64)
`users`	integer (int64)	Daily-rotating visitors: a person counts once per day (§19).

Usage

Field	Type	Description
`events_per_month`	integer (int64)
`from`	string
`org_events_this_month`	integer (int64)	Accepted events this calendar month for the whole org (the quota counts per org).
`outcomes`	object	Ingest outcomes for this app over the window (§6 ingest_counters).
`plan`	string
`to`	string

VerifyRequest

Field	Type	Description
`token`	string

Stats API

Auth

POST /auth/logout

POST /auth/magic-link

POST /auth/verify

GET /me

GET /me/sessions

DELETE /me/sessions/{id}

Apps

GET /apps

POST /apps

GET /apps/{id}

PATCH /apps/{id}

DELETE /apps/{id}

POST /apps/{id}/export

POST /apps/{id}/forwarding-secret

GET /apps/{id}/funnels

POST /apps/{id}/funnels

DELETE /apps/{id}/funnels/{funnel_id}

GET /apps/{id}/keys

POST /apps/{id}/keys

DELETE /apps/{id}/keys/{key}

GET /jobs/{id}