Stats API

The Stats API lets you read your Ometra analytics programmatically — aggregate numbers only, the same privacy-first data you see in the dashboard. It's read-only: there are no endpoints that change data or expose anything about individual visitors.

The API is available on the Individual and Agency plans.

Authentication

Create a key under Settings → API. You'll see the full token once — copy it then, because it's stored only as a hash and can't be shown again. Keys are scoped to a workspace and can read any site in it.

Send the key as a bearer token:

Authorization: Bearer oma_live_xxxxxxxxxxxxxxxxxxxxx

Owners and admins can create and revoke keys; revoking takes effect immediately.

Base URL & conventions

https://ometra.io/api/v1

• site_id is your site's domain (e.g. example.com).
• period is one of today, 7d, 30d, 12mo (default 30d). Ranges resolve in the site's configured timezone.
• All responses are JSON. Metrics are aggregate: bounce_rate is a fraction (0–1), visit_duration is in seconds.

Rate limits

600 requests per key per hour. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds). Over the limit returns 429 with a Retry-After header.

Endpoints

List sites

GET /api/v1/sites

{ "data": [ { "site_id": "example.com", "timezone": "America/Toronto" } ] }

Summary

Headline metrics for the range.

GET /api/v1/stats/summary?site_id=example.com&period=30d

{
  "site_id": "example.com",
  "period": "30d",
  "data": {
    "visitors": 12840,
    "visits": 15230,
    "pageviews": 39420,
    "views_per_visit": 2.59,
    "bounce_rate": 0.16,
    "visit_duration": 134
  }
}

Timeseries

One point per bucket (hour/day/month, chosen from the period).

GET /api/v1/stats/timeseries?site_id=example.com&period=30d

{
  "site_id": "example.com",
  "period": "30d",
  "interval": "day",
  "data": [
    { "date": "2026-08-01", "visitors": 420, "visits": 480, "pageviews": 1180, "views_per_visit": 2.46, "bounce_rate": 0.18, "visit_duration": 128 }
  ]
}

Breakdown

Top values of a property, ranked by visitors.

GET /api/v1/stats/breakdown?site_id=example.com&period=30d&property=source&limit=100

property is one of: source, channel, campaign, page, entry_page, exit_page, country, region, city, device, browser, os. limit defaults to 100 (max 1000).

{
  "site_id": "example.com",
  "period": "30d",
  "property": "source",
  "data": [
    { "name": "Google", "visitors": 5120 },
    { "name": "Direct", "visitors": 3480 }
  ],
  "meta": { "limit": 100 }
}

Realtime

Visitors active in the last 5 minutes.

GET /api/v1/stats/realtime?site_id=example.com

{ "site_id": "example.com", "data": { "visitors": 18 } }

Errors

Errors return the matching HTTP status and a JSON body { "error": "…" }:

Status	Meaning
400	Missing or invalid parameter (site_id, period, property).
401	Missing, malformed, or revoked API key.
403	The plan doesn't include API access.
404	No such site in this workspace.
429	Rate limit exceeded — see Retry-After.

Coming from Plausible

Ometra's API is its own (not a drop-in replacement for Plausible's), but the concepts map closely, so migrating is mostly mechanical:

• Plausible's /api/v1/stats/aggregate → /api/v1/stats/summary.
• /api/v1/stats/timeseries → /api/v1/stats/timeseries (metrics are returned together per point rather than one at a time).
• /api/v1/stats/breakdown with property=visit:source → /api/v1/stats/breakdown with property=source (drop the visit: / event: prefixes).
• /api/v1/stats/realtime/visitors → /api/v1/stats/realtime.
• Auth is the same shape: Authorization: Bearer <key>. Point your base URL at https://ometra.io/api/v1 and swap in an Ometra key.