umami-query

Umami Query

Query the Umami API for analytics data. All operations are read-only and execute directly.

Prerequisites

Read .umami.json from project root for host, websiteId, token. If missing, invoke bvdr:umami-setup.

Smart Defaults

• No date range specified → default to last 7 days
• User says "today" → calculate startAt/endAt for current day
• User says "this month" → first day of current month to now
• All startAt/endAt values are in milliseconds since epoch
• Calculate with: date +%s000 (bash) or Date.now() (JS)
• Format results as readable tables
• After showing results, suggest relevant follow-up queries

Endpoints

Website Stats

Overview metrics for a date range.

curl -s "{host}/api/websites/{websiteId}/stats?startAt={startMs}&endAt={endMs}" \
  -H "Authorization: Bearer {token}"

Response: { "pageviews": N, "visitors": N, "visits": N, "bounces": N, "totaltime": N, "comparison": {...} }

Active Visitors

Unique visitors in last 5 minutes.

curl -s "{host}/api/websites/{websiteId}/active" \
  -H "Authorization: Bearer {token}"

Response: { "visitors": N }

Pageviews Over Time

Time series of pageviews and sessions.

curl -s "{host}/api/websites/{websiteId}/pageviews?startAt={startMs}&endAt={endMs}&unit=day&timezone=Europe/Bucharest" \
  -H "Authorization: Bearer {token}"

unit values and limits:

• minute — max range: 60 minutes
• hour — max range: 30 days
• day — max range: 6 months
• month, year — no limit

Add &compare=prev for previous period comparison or &compare=yoy for year-over-year.

Response: { "pageviews": [{"x": "2026-03-01", "y": 150}], "sessions": [{"x": "2026-03-01", "y": 80}] }

Metrics Breakdown

Break down data by any dimension.

curl -s "{host}/api/websites/{websiteId}/metrics?startAt={startMs}&endAt={endMs}&type=path&limit=20" \
  -H "Authorization: Bearer {token}"

type values: path, entry, exit, title, query, referrer, channel, domain, country, region, city, browser, os, device, language, screen, event, hostname, tag, distinctId