Point an agent at your
own analytics.

Every request carries an API key as a bearer token. Mint one in Settings → API keys (organization admins only); the plaintext is shown exactly once at creation.

Authorization: Bearer rm_read_xxxxxxxxxxxxxxxxxxxx

Keys are scoped to a single organization and are read-only. A key may optionally be restricted to a subset of sites — anything outside that allowlist is invisible to it, indistinguishable from a site in another organization. The organization is derived from the key and can never be passed as a parameter.

The read API and MCP server are a Growth-and-above feature. A valid key on the Free or Starter plan authenticates but is answered with 403 plan_required.

A request that reaches further back than the plan's retention window is clamped, not rejected: from is moved forward to the earliest retained day and the response says so in meta.range_clamped and meta.requested_from.

The REST API is rooted at /api/v1; the MCP server is a single endpoint at /api/mcp. Both authenticate with the same key.

REST   https://rationalmetrics.io/api/v1
MCP    https://rationalmetrics.io/api/mcp

A first request end to end:

curl -s "https://rationalmetrics.io/api/v1/stats/summary?site=aB3xK9&range=7d" \
  -H "Authorization: Bearer rm_read_xxxxxxxxxxxx"

Every successful response is a data payload plus a meta block describing the window that was actually served — which may differ from what was asked for if the range was clamped.

{
  "data": [ ... ] | { ... },
  "meta": {
    "site": "aB3xK9",       // or null for org-wide / group scope
    "group": null,
    "from": "2026-07-07T00:00:00.000Z",
    "to": "2026-07-14T00:00:00.000Z",
    "range_clamped": false
    // "requested_from" is present only when range_clamped is true
  }
}

On endpoints with no time window (/sites, /stats/realtime), from and to are null.

Every error is a single error object with a stable code and a message written to be actionable — by a human or by a model reading it directly.

{ "error": { "code": "rate_limited", "message": "…" } }

A 401 means we don't know who you are; a 403 means we do and you may not. An unknown site is always a 404, never a 403 — a 403 would confirm the site exists.

Two layers. A per-key burst bucket absorbs the natural shape of agent traffic — a turn that fans out ten calls in a few seconds, then goes quiet — while a per-organization daily ceiling caps total spend across every key the org holds.

Cost is weighted by range, not by call count: a request spends 1 + floor(rangeDays / 30) tokens, so a 7-day summary costs 1 while a full-year breakdown costs 13. Long-range queries are self-limiting without being forbidden.

Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 adds Retry-After (seconds) and a message stating how long to wait.

Eleven read endpoints. Each maps one-to-one to an MCP tool of the same shape (the tool name is noted on each). Unless stated otherwise every stats endpoint accepts the shared window parameters below.

[
  {
    "site": "aB3xK9",
    "name": "Acme Marketing",
    "domain": "acme.com",
    "timezone": "UTC"
  }
]

{
  "uniqueVisitors": 4820,
  "pageviews": 9310,
  "engagedViews": 6740,
  "totalEvents": 512
}

{
  "buckets": [
    { "bucket": "2026-07-07", "visitors": 610, "pageviews": 1180 },
    { "bucket": "2026-07-08", "visitors": 705, "pageviews": 1322 }
  ]
}

[
  { "pathname": "/", "pageviews": 3120 },
  { "pathname": "/pricing", "pageviews": 880 }
]

[
  { "referrer": "news.ycombinator.com", "count": 412 },
  { "referrer": "google.com", "count": 388 }
]

[
  { "country": "US", "visitors": 2140 },
  { "country": "DE", "visitors": 610 }
]

[
  { "value": "Chrome", "count": 3010 },
  { "value": "Safari", "count": 1450 }
]

[
  {
    "source": "newsletter",
    "medium": "email",
    "campaign": "july-launch",
    "visitors": 240
  }
]

[
  { "value": "newsletter", "count": 240 },
  { "value": "twitter", "count": 180 }
]

[
  { "eventType": "signup", "count": 96 },
  { "eventType": "add_to_cart", "count": 61 }
]

{
  "visitors": 37,
  "pageviews": 52
}

Pass compare=true to /stats/summary or /stats/timeseriesto get the same-length period immediately before the window, plus the delta — so an agent doesn't have to make two calls and do arithmetic. Each compared value becomes:

{ "current": 1234, "previous": 1000, "change": { "abs": 234, "pct": 23.4 } }

• change.pct is null when the previous period was zero — that means there was no baseline, not zero change.
• For range=today the comparison is the same elapsed window yesterday (midnight → the same time yesterday), not all of yesterday.
• compare is not supported on the top-N endpoints in v1; passing it there is an invalid_request.

The same eleven handlers are exposed as an MCP server over stateless streamable HTTP at /api/mcp. There is nothing to install — point a remote-MCP-capable client at the URL and paste the key as a bearer token.

{
  "mcpServers": {
    "rational-metrics": {
      "url": "https://rationalmetrics.io/api/mcp",
      "headers": { "Authorization": "Bearer rm_read_xxxxxxxxxxxx" }
    }
  }
}

Tool results return the same data payload as the REST API, with meta folded into the tool text so the model sees the effective window it actually got. The eleven tools:

The dataset is pseudonymous by construction — the collector hashes and discards the IP and user-agent at ingest, so there is no PII to reason about. A few semantics matter when interpreting results:

• A visitor (uniqueVisitors) is a daily-salted pseudonymous identifier — not a person, and not stable across days (on strict-privacy sites, not even within a day). It is not a count of people or accounts.
• Engaged views are pageviews where a human was verifiably present, and are always ≤ pageviews. They are not interchangeable with pageviews.
• All dates and time buckets are UTC in v1.