umami-stats_skill

Overview

This skill provides a read-only data-access layer to query Umami Cloud (v2) analytics via API using an environment-provided API key. It supplies reusable Python query scripts, endpoint selection guidance, and presets for common time ranges so agents can fetch pages, events, sessions, realtime, reports, and attribution data. Use it to retrieve raw JSON that downstream agents can analyze, visualize, or include in reports.

How this skill works

The skill issues GET requests to Umami endpoints, mapping cloud vs self-hosted paths and applying the correct authentication header automatically. It supports presets (today, last7d, last30d) or explicit startAt/endAt timestamps, auto-inserts websiteId when available, and defaults metrics type to url when required. Scripts expose a flexible --endpoint/--param interface so callers can call any supported read endpoint and return JSON for further processing.

When to use it

• Fetch website traffic, pageviews, event series, sessions, realtime, or attribution data for analysis or monitoring.
• Build datasets for experiments, A/B tests, or marketing planning using raw Umami metrics.
• Compare time windows (current vs previous period) or produce trend reports for stakeholders.
• Power dashboards or automated alerts with periodic pulls of Umami statistics.
• Inspect specific events or user interactions before designing UX changes.

Best practices

• Keep all requests read-only (GET) to avoid modifying analytics data.
• Prefer explicit startAt and endAt timestamps for reproducibility rather than implicit presets when saving queries.
• Set UMAMI_API_KEY and UMAMI_BASE_URL in the environment; use UMAMI_WEBSITE_ID to default target site.
• Use cloud (/v1) endpoints for Umami Cloud and /api for self-hosted; the script auto-maps common legacy paths.
• Check API docs (https://v2.umami.is/docs/api) for endpoint-specific params and required query keys (e.g., metrics type).

Example use cases

• List all configured websites to determine the correct websiteId before running queries.
• Pull last 7 days of website stats to compare sessions and pageviews week-over-week.
• Query top pages for the last 30 days to prioritize content updates or SEO experiments.
• Retrieve event series for signup clicks to analyze conversion funnels and identify drop-off timing.
• Schedule a nightly job that pulls core KPIs and feeds them to a BI tool or alerting system.