API reference

The API Worker serves every endpoint on this page from the same origin as the dashboard. The examples use https://analytics.example.com. The MCP server has its own page, Ask AI tools about your traffic.

#Authentication

Send a bearer token in the Authorization header:

curl -H "Authorization: Bearer mm_..." "https://analytics.example.com/api/v1/stats/aggregate?site=shop&period=7d"

The API reads tokens from the header only. A token in the query string is ignored, so a key never lands in logs or browser history. Requests without a token can read public sites, such as the demo.

#Who may call a route

The Role column in the tables below names the least access a route needs.

A team role covers every site of the team. A guest role covers one site. The billing role has no site permissions, so a billing member reads no stats. An API key has its owner's role, and a key limited to one site has no role on any other site.

#Errors

Every error is JSON with one field:

{ "error": "unknown property: pagee" }

/mcp answers JSON-RPC requests with JSON-RPC errors (Ask AI tools about your traffic). A payment webhook answers {"error": ...} with its own statuses, listed in Payment webhooks.

#Rate limits

/api/v1/stats/* and /api/v2/query allow 100 requests per minute per API key, or per IP address for requests without a key (STATS_LIMIT). Signed-in dashboards and shared links are not limited.

POST /api/v1/share/:slug, POST /api/v1/auth/signup, POST /api/v1/auth/login, POST /api/v1/auth/forgot, POST /api/v1/auth/reset, and POST /api/v1/invitations/:token/accept use the same limit per IP address, counted separately for each route. Over it, they return 429 with too many attempts, wait a minute.

#Query parameters

All GET /api/v1/stats/* endpoints accept these parameters.

Days, weeks, and months follow the site's time zone, including daylight saving changes.

#Filters

A filter string holds up to 8 filters separated by ;. Each filter is a dimension, an operator, and up to 6 values separated by |. A query holds at most 16 values in total.

country==US|CA;page~/blog;browser!=Safari

In == and !=, * is a wildcard: page==/blog/*. The value (none) matches rows with no value, for example referrer==(none).

Dimensions: page, entry_page, exit_page, hostname, event, goal, source, referrer, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, country, region, city, continent, timezone, network, browser, browser_version, os, os_version, device, screen, language, and prop:<name> for a custom property. A property name is 1 to 64 letters, digits, _, ., or -. GET /api/v1/meta/dimensions returns the full list as key and label pairs, without goal. It is Public.

goal==Signup filters by the saved goal named Signup: its page or its event. One goal filter can't mix page goals and event goals.

channel takes one of Direct, Organic Search, Paid Search, AI Assistants, Organic Social, Paid Social, Email, Video, Affiliates, Display, and Referral.

#Stats endpoints

Every stats endpoint needs Viewer on the site.

#GET /api/v1/stats/aggregate

The headline metrics for the period.

{
  "current": { "visitors": 3361, "visits": 4286, "pageviews": 9332, "views_per_visit": 2.18, "bounce_rate": 48.9, "visit_duration": 96, "events": 1830, "revenue": 5192, "average_revenue": 40.9 },
  "previous": { "visitors": 2453, "...": "..." },
  "change": { "visitors": 37.2, "bounce_rate": 2.2, "...": "..." }
}

visitors counts unique visitors per day. bounce_rate is a percentage of visits. visit_duration is in seconds, from the first to the last pageview or custom event of a visit. change is the percent change of each metric, except bounce_rate, which changes in percentage points. previous and change are null without compare. The response also has site and window (from and to in milliseconds).

#GET /api/v1/stats/timeseries

All headline metrics per time bucket. Returns interval, window (from and to in milliseconds), points, and previous (null without compare). Each point has t, the bucket start in milliseconds, and the same fields as current above. Empty buckets are returned as zeros.

#GET /api/v1/stats/breakdown

The top values of one dimension. Extra parameters:

Returns property, rows, total_visitors, and has_more. Each row has key, visitors, visits, pageviews, events, bounce_rate, and visit_duration. Rows of page also have time_on_page (seconds) and scroll_depth (percent). Rows of exit_page also have exit_rate. Rows of event, goal, props, and prop:<name> also have conversion_rate, revenue, and average_revenue. Goal rows also have kind and match. Rows of visit dimensions, such as source, have revenue and average_revenue when the visits had revenue.

search_term rows have key, clicks, impressions, ctr (percent), position (the average position, 1 is the top), and visitors, which holds the clicks. They come from Google, live, and stay cached for ten minutes. For a site without Search Console, search_term returns 409.

A response with truncated: true came from a shard that had more rows than its cap of 500, so the rarest rows may be missing.

#GET /api/v1/stats/realtime

Visitors in the last 5 minutes, pageviews per minute for the last 30 minutes, the top pages, sources, and countries right now, and a feed of recent events. It ignores period.

#GET /api/v1/stats/vitals

For each Core Web Vital (lcp, inp, cls, fcp, ttfb): the 75th percentile, the number of samples, and the counts rated good, needs improvement, and poor. LCP, INP, FCP, and TTFB are in milliseconds.

#POST /api/v1/stats/funnel

Runs a funnel over the period. The body takes the query parameters as JSON fields (site, not site_id), plus steps (2 to 8) and mode:

{
  "site": "shop",
  "period": "30d",
  "mode": "sequential",
  "steps": [
    { "kind": "page", "match": "/" },
    { "kind": "page", "match": "/pricing" },
    { "kind": "event", "match": "Signup", "label": "Signed up" }
  ]
}

Each step has kind (page or event), match (a path or an event name, cut to 200 characters), and an optional label (cut to 80). In place of steps, funnel takes the id of a saved funnel and runs its steps and mode. A mode in the body overrides the saved one.

A missing or unknown mode is sequential. Returns mode, entered, completed, and steps. Each step has label, visitors, conversion (percent of the first step), and dropoff.

#GET /api/v1/stats/journeys

The next or previous page after a path. Extra parameters: path (comma-separated pages, for example /,/pricing), direction (forward or backward), and limit (1 to 50, default 12). Rows include (exit) and (entrance) for the ends of a visit. Reloads of the same page count once.

#GET /api/v1/stats/behavior

What people did on pages, from the engagement beacon (tracking guide). Extra parameters: report (required), page (one path without ; or |, which replaces any page filter), and limit (default 50, at most 500 rows).

curl -H "Authorization: Bearer $KEY" \
  "https://app.misomoon.com/api/v1/stats/behavior?site=shop&period=30d&report=clicks&page=/pricing"

A response with truncated: true came from a shard that had more rows than the cap, so the rarest rows may be missing.

#GET /api/v1/stats/export

A ZIP file with one CSV file per report for the period and filters. The file is named misomoon_<site>_<from>_<to>.zip, with the first and last day of the period.

Each breakdown file holds at most 1000 rows.

#Stats API v2

POST /api/v2/query takes one JSON query and returns rows. It supports no dimension, one time dimension, or one property dimension. It needs Viewer on the site.

{
  "site_id": "shop",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "7d",
  "dimensions": ["visit:source"],
  "filters": [["is", "visit:country", ["US", "CA"]]],
  "order_by": [["visitors", "desc"]],
  "pagination": { "limit": 20, "offset": 0 }
}

Property dimensions: event:page, event:hostname, event:name, event:goal, visit:entry_page, visit:exit_page, visit:source, visit:referrer, visit:channel, visit:utm_source, visit:utm_medium, visit:utm_campaign, visit:utm_content, visit:utm_term, visit:device, visit:browser, visit:browser_version, visit:os, visit:os_version, visit:country, visit:region, visit:city, visit:screen, and event:props:<name>. visit:country_name, visit:region_name, and visit:city_name return the same values as visit:country, visit:region, and visit:city. A property dimension returns at most the top 200 values by visitors.

Filter operators are is, is_not, contains, contains_not, matches_wildcard, and matches_wildcard_not. Filters take the same dimensions. matches_wildcard is is with * as a wildcard, as in Filters.

The response is {"results": [{"dimensions": [...], "metrics": [...]}], "meta": {...}, "query": {...}}. metrics follow the order of the query's metrics. A time dimension's label is the bucket start in UTC, as YYYY-MM-DD HH:MM:SS for time:minute and time:hour and as YYYY-MM-DD otherwise.

#Sites

A site object has id, domain, name, timezone, currency, team_id, public (0 or 1), ingest_cap, features, search_params, include_paths, exclude_paths, exclude_ips, privacy_signals (0 or 1), retention_days, and created_at in milliseconds.

#Add a site

POST /api/v1/sites takes:

Without team, the site goes to the first team you joined as owner, admin, or editor. If you have none, the server makes a team named My sites with you as owner. API keys can't add sites. A domain or id that is already taken returns 409.

#Goals

The body takes kind (event or page, required), match (required: the event name, or the page path, where * is a wildcard), and name. match is cut to 200 characters. name is cut to 80 and defaults to match. A site has at most 50 goals, and the 51st returns 400. A name the site already uses returns 409.

#Funnels

The body takes name (required, cut to 80 characters), steps (at least 2, and only the first 8 are kept), and mode (sequential, strict, or flexible, default sequential). Steps take the same fields as in POST /api/v1/stats/funnel.

#Segments

A segment is a saved filter string. A site segment is shared with everyone who can read the site. A personal segment is visible to its author only, so a viewer can save one.

The body takes name (required, cut to 80 characters), filters (required, a filter string), and personal (true for a personal segment). A segment with the same name and owner gets the new filters and keeps its id.

#Annotations

Notes on the chart, such as deploys.

The body takes text (required, cut to 200 characters), ts (milliseconds or an ISO date, default now), and source (cut to 40 characters, default manual). An API key whose owner is an editor may post one, so CI can mark deploys:

curl -X POST "https://analytics.example.com/api/v1/sites/shop/annotations" \
	-H "Authorization: Bearer $MISOMOON_KEY" -H "Content-Type: application/json" \
	-d '{"text": "Deployed v2.3.0", "source": "ci"}'

#Shared links

A shared link opens a read-only dashboard of one site, with an optional password, segment, and expiry.

The body of POST /api/v1/sites/:id/shared takes name (cut to 80 characters, default Shared link), password, segment_id (a segment applied to every query through the link), and expires_days (at most 3650). Without expires_days, the link never expires.

#Email reports and alerts

The body of POST /api/v1/sites/:id/reports takes email (required), kind (required), and threshold, a whole number. A threshold out of range returns 400. A second subscription for the same email and kind replaces the threshold.

#Imports

Imported history from a CSV export or a Google Analytics property. Unfiltered reports add it to the site's own data. Every route needs Editor.

POST /api/v1/sites/:id/imports takes multipart/form-data with one or more file fields: a ZIP of the export, or its CSV files. A file counts when its name is imported_<table>.csv or imported_<table>_YYYYMMDD_YYYYMMDD.csv. The tables read are visitors, sources, pages, entry_pages, exit_pages, locations, browsers, operating_systems, devices, and custom_events. A request with no such file returns 400. While the site's history moves between shards, an import returns 409. Try again a few hours later.

For a Google import, open the URL from POST /api/v1/sites/:id/imports/google/connect. Google returns the person to the dashboard settings with google=<grant id> in the URL. Google sign-in must finish within an hour of the connect call. POST /api/v1/sites/:id/imports/google takes grant (required), property (required, properties/123), from and to (YYYY-MM-DD, default the earliest day Google serves and yesterday in UTC), and label. The server deletes the grant when the import finishes. Without Google configured, these routes return 501.

#Google Search Console

The connected Search Console property feeds property=search_term in GET /api/v1/stats/breakdown. Every route needs Editor.

#Payment webhooks

PUT takes {"secret": "whsec_..."}, the signing secret, which stripe, polar, and dodo require. For lemonsqueezy and custom, a secret is optional and needs at least 16 characters. Without one, the server makes a secret and returns it once as secret. An unknown provider returns 404.

The webhook returns 404 for an unknown provider or a site without that webhook, 413 for a body over 256 KB, 401 when the signature does not match the saved secret, and 400 for a body it can't read. Connect payments lists the events each provider sends and the body for custom.

#Managed proxy

The site's own subdomain, such as stats.example.com, pointed at misomoon with a CNAME (Serve the tracker from your own domain). Every route needs Editor.

Without Cloudflare for SaaS configured, PUT returns 501 and available is false. A Cloudflare API error returns 502.

#Accounts and teams

Roles, from most to least access: owner, admin, editor, viewer, and billing. Architecture lists what each role can do.

#Sign-in

POST /api/v1/auth/signup takes email, password, and name (cut to 80 characters, default the part of the email before @). It creates a team named <name>'s sites with you as owner, and returns 201 with token, expires_at, and user. An email that already has an account returns 409. Whether sign-up is open depends on SIGNUPS (Variables):

A password has 10 to 200 characters. POST /api/v1/auth/forgot always returns {"ok": true, "sending": ...}, whether or not the email has an account. sending is false without an email provider. The link works for an hour and replaces any earlier link. POST /api/v1/auth/reset takes token, the code from the link, and password. It signs out every other session of the account and returns a new token and expires_at. An expired link returns 400.

#Your account

GET /api/v1/me returns:

#API keys

#Teams and members

A :user who is not on the team returns 404. An admin can't make an owner, change an owner's role, or remove an owner (403). A change that would leave the team without an owner returns 409.

#Invitations

POST /api/v1/teams/:team/invitations takes email, role, and site:

• Without site, it invites a team member. It needs a session that is team owner or admin, and role is a team role. Only an owner can invite an owner. An email that is already on the team returns 409.
• With site, it invites a guest to that one site. It needs Admin on the site, which must belong to the team, and role is editor or viewer.

A new invitation for the same email and site replaces the earlier one. The link in url works for 7 days. The server emails it and sets sent to whether the email went out, so the link can be passed on another way.

To accept, a person signed in with the invited email sends no body. Signed in with another email, the request returns 403. Without a session, the body takes name and password, and the server creates the account for the invited email and also returns token and expires_at.

#Guests

#Event ingestion

POST /api/event takes one event as JSON. The tracker sends it as text/plain so the browser makes no preflight request. The response is always 202, even for an event that is dropped, so the endpoint reveals nothing about which sites exist. Events past a site's daily cap are dropped too (Daily ingest cap). It is Public. OPTIONS /api/event answers a preflight with 204.

The server removes emails, ids, tokens, and numbers of 6 or more digits from q and from the text in the interaction lists. Form fields carry names and flags, never values. Pageviews and engagements on a path that the site's include_paths or exclude_paths leave out are dropped.

Bodies over 16 KB are dropped. Bots are dropped by Cloudflare's bot signals and by user-agent patterns.

A server that sends events for a visitor sets X-Misomoon-Ip to the visitor's address and User-Agent to the visitor's user agent. X-Misomoon-Country, -Region, -City, -Continent, and -Timezone carry the location, URL-encoded. These are the headers a first-party proxy sets. An app sends a user agent of the form MisomoonApp/<sdk version> (<platform>) <app name>/<app version>, and reports show the app name in place of the browser. The SDK guide covers both.

GET /api/health returns 200 with {"ok": true} when the Worker is up.

#Tracker files

On a managed proxy hostname, the Worker serves /m.js, /overlay.js, and /api/event only. Every other path returns 404.

#MCP endpoint

POST /mcp takes JSON-RPC 2.0 requests from MCP clients, with the same bearer tokens as the API. A batch holds at most 20 requests, and a body over 64 KB returns 413. GET /mcp returns 405, because the server does not stream. Ask AI tools about your traffic lists the tools and the client setup.