umami

Original：🇺🇸 English
Translated
1 scripts

Fetch analytics from Umami. Use when the user asks about umami, analytics, website traffic, daily stats, pageviews, visitors, how is my site doing, traffic report, site performance, bounce rate, visitor count, active users, who is on my site, or website statistics.

2installs
Sourcemartinhjartmyr/skills
Added on

NPX Install

npx skill4agent add martinhjartmyr/skills umami

Tags

Translated version includes tags in frontmatter
umami-analyticswebsite-trafficdata-processingbash-scriptapi-integration

SKILL.md Content

View Translation Comparison →

Umami Analytics

Fetch traffic summaries and analytics data from an Umami instance.

Configuration

Set these environment variables before running:
VariableRequiredDescription
UMAMI_API_URL
YesBase URL of your Umami instance (e.g. 
https://cloud.umami.is
)
UMAMI_API_KEY
One of theseAPI key for Umami Cloud. Used as Bearer token directly.
UMAMI_USERNAME
One of theseUsername for self-hosted login via 
/api/auth/login
.
UMAMI_PASSWORD
With usernamePassword for self-hosted login.
If 
UMAMI_API_KEY
is set, it takes precedence over username/password.

Workflow: Daily Traffic Summary

  1. Run the script:
    bash
    bash ~/Projects/skills/umami/scripts/umami-summary.sh
  2. Parse the JSON output.
  3. Format as a markdown table:
WebsiteDomainPageviewsVisitorsVisitsBouncesAvg TimeActive
My Blogblog.example.com1,234 (980)567 (510)890 (801)123 (110)45s (38s)3
Totals1,234 (980)567 (510)890 (801)123 (110)45s (38s)3
  • Show previous period values in parentheses after each metric (e.g. "1,234 (980)" means 1,234 current, 980 previous).
  • Format numbers with commas for readability.
  • Convert 
    totaltime
    to human-readable duration (e.g. "1m 23s").
  • Calculate average time as 
    totaltime / visits
    for each site, using 
    prev_totaltime / prev_visits
    for the previous period.
  • Bold the totals row.

Workflow: Active Users Only

For "who is on my site right now?" queries, use the lightweight flag:
bash
bash ~/Projects/skills/umami/scripts/umami-summary.sh --active-only
This skips the stats API calls and only fetches current active visitor counts. Format as a simpler table:
WebsiteDomainActive
My Blogblog.example.com3

Error Handling

The script exits non-zero and writes JSON to stderr on failure:
  • Missing env vars: 
    {"error": "UMAMI_API_URL is not set"}
  • Auth failure: 
    {"error": "Authentication failed (HTTP 401)"}
  • Unreachable server: 
    {"error": "Could not connect to https://..."}
Report these errors clearly to the user with the specific message. Suggest checking their environment variables.

API Reference

For queries beyond the daily summary (time series, metrics breakdowns, custom date ranges), see references/api.md.