umami-stats

✓Verified·Scanned 2/18/2026

This skill fetches Umami analytics via the scripts/umami_query.py helper using the UMAMI_API_KEY and https://api.umami.is (or a self-hosted base-url). It reads UMAMI_API_KEY, invokes python3 scripts/umami_query.py, and performs HTTP requests; these behaviors are purpose-aligned and no unexpected exfiltration was detected.

from clawhub.ai·va42014e·15.2 KB·0 installs
Scanned from 1.0.0 at a42014e · Transparency log ↗
$ vett add clawhub.ai/hfichter/umami-stats

Umami Stats (Read-only API skill)

Use this skill as a data-access layer: fetch Umami analytics data, then let the agent decide analysis/strategy.

Required environment variables

  • UMAMI_API_KEY (required)
  • UMAMI_BASE_URL (optional, default: https://api.umami.is)
  • UMAMI_WEBSITE_ID (optional default site)
  • UMAMI_DEPLOYMENT (optional: cloud or self-hosted, default: cloud)

API path conventions (explicit)

  • Umami Cloud: https://api.umami.is/v1/...
  • Self-hosted Umami: https://<your-host>/api/...

The script supports both:

  • --deployment cloud → uses cloud behavior (/v1 + x-umami-api-key)
  • --deployment self-hosted → uses self-hosted behavior (/api + Authorization: Bearer ...)

Read-only workflow

  1. Pick endpoint from docs or references/read-endpoints.md.
  2. Run scripts/umami_query.py with endpoint + params.
  3. Use presets (today, last7d, etc.) or custom startAt/endAt.
  4. Analyze returned JSON for the user task.

Quick commands

# 1) List websites
python3 scripts/umami_query.py --endpoint /v1/websites

# 2) Website stats for last 7 days (default website from env)
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/stats \
  --preset last7d

# 3) Top pages with explicit website id
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/pageviews \
  --website-id "$UMAMI_WEBSITE_ID" \
  --preset last30d

# 4) Events series with custom window
python3 scripts/umami_query.py \
  --endpoint /v1/websites/{websiteId}/events/series \
  --param startAt=1738368000000 \
  --param endAt=1738972799000

# 5) Legacy path auto-mapping in cloud mode (/api/... -> /v1/...)
python3 scripts/umami_query.py --endpoint /api/websites/{websiteId}/stats --preset last7d

# 6) Self-hosted example (/v1/... auto-maps to /api/...)
python3 scripts/umami_query.py \
  --deployment self-hosted \
  --base-url "https://umami.example.com" \
  --endpoint /v1/websites/{websiteId}/stats \
  --preset last7d

Natural trigger examples

  • “How was traffic this week?”
  • “Top pages in the last 30 days”
  • “Show event trends for signup clicks”
  • “Compare current week vs previous week”
  • “Give me raw Umami data to build a marketing experiment plan”

Notes

  • Keep requests read-only (GET).
  • Prefer explicit time windows for reproducibility.
  • For unknown endpoints, consult https://v2.umami.is/docs/api and then query with the script.
  • Prefer /v1/... endpoints in cloud mode, /api/... in self-hosted mode.
  • Auth headers are mode-specific: cloud uses x-umami-api-key; self-hosted uses Authorization: Bearer ....
  • metrics endpoints require a type query param. The script now auto-defaults to type=url if omitted.
  • For /v1/reports/* endpoints, the script auto-adds websiteId from --website-id / UMAMI_WEBSITE_ID when available.
  • On Umami Cloud, /v1/users/* endpoints can return 403 for normal user API keys (expected in many accounts).

Resources

  • Endpoint map: references/read-endpoints.md
  • Query helper: scripts/umami_query.py